Cache and Release Classification Grill Log

Context

Source research: Cache Sharing and Diff-Classified Release Research.
Reopened-fidelity research: Maximal Test Caching and Green-Main Release Gate Research, commit eabdd5f7206f0aeeb3a3aaba4ff31de5dc30d1f8 on research/cache-release-green-main-gaps.
Prior authority: Turborepo Release Caching Grill Status and Log.
This grill extends the closed cache work to platform-neutral deterministic tests, semantic release classification, automatic stable publication from main, merge gates, and release credentials.

Prior Status Summary

Accepted and retained:

Local development and same-repository PR CI share a signed development cache.
Fork PRs receive no cache credentials.
Protected and release jobs use a separate signed authority and never consume development-cache artifacts.
Release mutations are uncached.
Existing-version retries reconcile immutable external state instead of republishing npm.

Rejected and retained:

Release mutations are never cacheable.
Fork PRs cannot read or write authenticated shared cache entries.
Protected release evidence cannot trust a developer-cache artifact.

Superseded:

Prior Q14 required OS and architecture in every reusable task identity. The user now accepts a platform-neutral identity for tests that are proven independent of platform. Host-shaped and release-artifact tasks retain host identity.
Q7 and Q18 limited the portable cache to deterministic CLI tests and typecheck while leaving native, ambient, build, and update work outside the shared policy. The user's cache-maximization correction supersedes that boundary in Q21: host-dependent work should be capability-keyed, and uncached execution needs a concrete freshness reason.
Q5 and Q9 required enforceable branch protection before automatic publication. Q24 supersedes that paid-plan dependency: the project uses only GitHub Free capabilities and makes exact successful pull-request evidence a publisher precondition instead of a merge precondition.

Unparked:

External release reconciliation is now part of the automatic stable release requirement.

Still parked:

Beta, canary, and staged release channels.

Confirmed Input Decisions

Q1

Prerequisites:

none

Question: Should a push to main after every feature-branch merge run the release classifier and automatically publish every required stable product release?

Accepted answer:

Yes.
Every merge to main runs the classifier.
The workflow mutates baseline or npm state only when the classifier requires it.

Q2

Prerequisites:

none

Question: Which public release channels are in scope?

Accepted answer:

Production stable only.
Beta, canary, and staged approval channels are out of scope.

Q3

Prerequisites:

none

Question: May an unchanged stable baseline cover a later CLI patch when consumer tests prove compatibility?

Accepted answer:

Yes.
A CLI-only compatible patch may publish npm without publishing unchanged baseline content.
The exact compatibility-range representation remains open in Q6.

Q4

Prerequisites:

none

Question: May platform-independent tests share cache entries between authenticated local development and same-repository PR CI?

Accepted answer:

Yes.
PR commits may populate the same signed development cache over time.
The exact portable task boundary remains open in Q7.

Q5

Prerequisites:

none

Question: Should the feature-branch-to-main workflow use enforceable merge gates?

Accepted answer:

Yes.
The exact required checks and bypass policy remain open in Q9.

Superseded by Q24:

Pull-request checks remain the intended workflow, but the project does not pay for branch protection. Exact green candidate evidence gates publication rather than the merge itself.

Research Facts for Round R1

An unbounded range such as >=3.1.8 asserts compatibility with every future CLI version, including untested minor and major versions.
A bounded range such as >=3.1.8 <3.2.0 permits future patch releases by policy; each npm release can still run the exact stable-baseline consumer matrix before publication.
Vercel CLI can inject one linked project's production variables directly into a child process with vercel env run -e production -- <command> without writing an env file.
Vercel CLI access from GitHub Actions still requires Vercel authentication. Vercel-issued OIDC is for workloads running on Vercel; it is not a GitHub-to-Vercel CLI login mechanism.
npm trusted publishing can bind npm publish to one GitHub Actions workflow through OIDC, removing the long-lived NPM_TOKEN from the publication step.

Round R1 Decisions

Q6

Prerequisites:

Question: What compatibility range may a stable baseline declare?

Accepted answer:

Use a compatible patch family.
A baseline range starts at its current supported CLI version and ends before the next minor version, for example >=3.1.8 <3.2.0.
Do not use an unbounded lower-only range such as >=3.1.8.
Every CLI patch publication still runs the exact stable-baseline consumer matrix.

Q7

Prerequisites:

Question: Which verification tasks use the platform-neutral development-cache identity?

Accepted answer:

CLI deterministic tests and CLI typecheck use the portable identity.
Keep exact Node, Bun, controlled environment, source, fixture, and declared dependency inputs.
Operating system, architecture, and the local-versus-CI marker do not divide the portable identity.
Production build, native, ambient, complete, and explicit uncached-update tasks retain their existing host-shaped or uncached policy.

Superseded by Q21:

The last bullet was too broad. Q21 replaces it with cache-by-default behavior classes and a minimal explicitly fresh set.

Q8

Prerequisites:

Question: Where is release version and changelog intent declared before automatic publication?

Accepted answer:

Pull requests declare release intent; CI does not invent versions.
npm intent requires the reviewed CLI package version and matching CHANGELOG.md entry.
Baseline intent requires the exact baseline tag, compatible patch range, and matching BASELINE_CHANGELOG.md entry.
The post-merge workflow reads and verifies the committed intent before publication.

Q9

Prerequisites:

Question: Which main protection rules are mandatory, and what happens when the repository plan cannot enforce them?

Accepted answer:

Require pull requests, the behavior-contract aggregate, CLI development verification, release-impact classification, and an up-to-date branch.
Block force pushes and branch deletion.
Do not require a human reviewer for the current solo feature-branch workflow.
Retain an audited owner emergency bypass.
Automatic production publication remains disabled until the repository plan can enforce the required gates.

Superseded by Q24:

GitHub Free cannot enforce these private-repository rules, and the project will not upgrade. Automatic publication instead fails closed unless the exact main tree has successful pull-request candidate evidence.

Q10

Prerequisites:

Question: How does the automatic baseline publisher receive Vercel-owned production variables?

Accepted answer:

Use the existing Devpunks Vercel organization and the existing project that owns the baseline production variables.
Do not create a separate release-authority project.
GitHub stores the Vercel access token, Devpunks organization ID, and selected project ID needed by the release job.
vercel env run -e production injects the Vercel environment only into the baseline-promotion child; builds, tests, and npm publication do not inherit unrelated production variables.
Live verification on 2026-08-10 identifies the existing project as Devpunks scope dev-punks, project harness-intelligence-api, project ID prj_Us1K3pmpyCJiAGLQfiPpAoOBhHGt, and organization ID team_0QvyOroTH1I7k8hWMqSRCOqH. Token values remain secret and are never recorded.

Q11

Prerequisites:

Question: How does automatic npm publication authenticate?

Accepted answer:

Use npm Trusted Publishing bound to the exact GitHub Actions release workflow and production release environment.
Bind it to the existing case-sensitive Production GitHub environment. The environment is an OIDC trust selector, not an approval gate.
Permit npm publish; do not permit staged publication.
Use a GitHub-hosted runner with OIDC and no long-lived npm publication token.
After one proven OIDC publication, disallow bypass-2FA tokens for the package and revoke the old automation token.

Q11 Browser Inspection — 2026-08-10

@punks/cli is currently published at 3.1.9.
No Trusted Publisher connection is configured.
Current package publishing access permits either 2FA or a granular access token with bypass-2FA enabled.
The npm GitHub Actions publisher form requires organization/user, repository, workflow filename, and optionally a GitHub environment; it can grant npm publish without granting npm stage publish.
The settings were inspected read-only. No npm connection, token, or package setting was created, updated, or revoked.

Round R2 Decisions

Q12

Prerequisites:

Question: What happens when a CLI patch fails the active stable-baseline consumer matrix, or when the CLI reaches the next minor version?

Accepted answer:

A failed exact consumer proof blocks an npm-only patch release.
The pull request must declare a mixed release with a compatible baseline and its required baseline intent.
Every new minor starts a new compatible patch family, for example >=3.2.0 <3.3.0.

Q13

Prerequisites:

Question: What proof is required before a task may join the platform-neutral cache class?

Rejected answer:

Do not require a bilateral forced-fresh macOS-to-Ubuntu and Ubuntu-to-macOS cache-hit proof.
The user considers that platform-heavy mechanism disproportionate.
A task joins the portable class through explicit task policy: deterministic CLI tests and CLI typecheck exclude platform-specific inputs and behavior.
No separate cross-platform qualification suite is required.

Q14

Prerequisites:

Question: When several merges reach main during a release, must every intermediate product version publish, or may pending work coalesce to the newest desired state?

State: unanswered.

Q15

Prerequisites:

Question: What order must a mixed baseline and npm release follow?

Accepted answer:

Keep the mixed release operational sequence simple: build the baseline, publish the stable baseline, then publish the npm package.
Do not add candidate upload, delayed promotion, or a release-authority service.
Q19 isolates the remaining next-minor availability tradeoff because an exact next-minor family cannot accept the currently installed prior-minor CLI.

Q16

Prerequisites:

Question: What must happen to npm's latest and next dist-tags in a production-only release model?

Accepted answer:

latest is the production dist-tag.
next is an alias of latest; each successful production publication reconciles both tags to the same version.
No beta or canary tag is introduced.

Q17

Prerequisites:

Question: How is npm Trusted Publishing activated without exposing the first automatic release to missing trust configuration?

Accepted answer:

Merge the automatic release workflow in a dormant state first.
Configure npm Trusted Publishing for the exact workflow filename and GitHub production environment.
Enable automatic publication in a later reviewed merge after the trust configuration is visible.
Prove the first OIDC publication, then disallow bypass tokens and revoke the legacy automation token.

Round R3 Decisions

Q14

Prerequisites:

Question: When several merges reach main during a release, must every reviewed product version publish, or may pending work coalesce to the newest desired state?

Accepted answer:

Preserve every product version explicitly reviewed in a pull request.
Serialize publication in version order; do not silently coalesce a pending reviewed version into a later merge.

Q18

Prerequisites:

Question: Who may write portable development-cache entries?

Accepted answer:

Authenticated local development and same-repository PR CI may both read and write the shared portable cache.
The portable cache contains only deterministic CLI tests and CLI typecheck.
Platform-specific, native, ambient, build, complete, and uncached-update tasks remain outside that portable identity.
Local and CI runs build the portable cache together; local development is not read-only.

Superseded by Q21:

Local and CI remain joint readers and writers, but the cache is no longer limited to the two named tasks. Q21 defines portable and capability-keyed classes for the remaining cacheable work.

Q19

Prerequisites:

Question: At a next-minor mixed release, does the team accept that publishing the new stable baseline before npm temporarily makes stable incompatible with installed prior-minor CLIs?

Accepted answer:

Yes.
Keep the simple baseline-first order at a next-minor mixed release.
The temporary interval where the new stable baseline rejects installed prior-minor CLIs is an accepted operational tradeoff.

Round R4 Decisions

Q20

Prerequisites:

Question: If publication of one reviewed version fails, must later reviewed versions wait while the failed version retries and reconciles its already-completed external steps?

Accepted answer:

A failed reviewed version remains first in the serialized release queue.
A retry verifies and reconciles already-completed external steps, then continues from the first missing step.
Later reviewed versions wait; no reviewed version is skipped or coalesced.
The failed GitHub production workflow is the required failure signal; no separate release service or alert system is introduced.

Reopened Research Facts for Round R5

The complete retained Actions history is 384 runs: 319 pull-request runs, 62 pushes, and 3 manual dispatches. No scheduled run exists in retained history.
Only three verified cases passed on a pull request and then failed on main. All three were protected-only cache authentication, attestation topology, or timeout failures while the protected graph was converging. PR #115 then proved the corrected graph green in both places.
PRs #119 and #120 were already red before merge. Seven later failing main commits had no associated pull request. Branch enforcement, not hidden post-merge product coverage, is the dominant gap.
The private repository belongs to a GitHub Free organization. Live branch-protection and ruleset requests both return HTTP 403. Private organization repositories need GitHub Team or Enterprise for enforceable protected branches.
The current PR root graph is diff-aware while main runs the full graph. Protected attestation also changes cache authority and release-shaped environment. That means the current PR proof is not the same proof later required for publication.
The deterministic CLI class still contains tests that branch on process.platform. Those tests must move to a capability-keyed class, or control their platform behavior, before the remaining class can safely share macOS and Ubuntu cache entries.
The 25-case update:uncached shard has no identified irreducible scheduling dependency; it can become capability-keyed. Most of the 45-case ambient file is controlled filesystem behavior and can move too. Only actual concurrent writers, lock contention, and elapsed-time assertions need fresh execution.
Generic workspace tests mix pure tests with Docker/Postgres, real child signals, loopback servers, and runtime-product checks. They require portable, capability-keyed, and minimal live/fresh classes before shared-cache credentials are added.
There is no pre-commit or pre-push test hook. The current affected selector compares commits, so a complete local graph is the safe fallback for uncommitted changes.

Round R5 Decisions

Q21

Prerequisites:

Question: How aggressively should test and build work use shared caching?

Accepted answer:

Cache verification work by default.
Portable work may share signed development-cache entries between authenticated local macOS and same-repository Ubuntu PR CI after platform-sensitive cases are removed or controlled.
Host-dependent filesystem, subprocess, signal, container, and native work uses capability-keyed cache entries instead of being broadly uncached.
Reclassify the update shard and controlled ambient cases into capability-keyed tasks.
Replace full forced-fresh native repetition with capability-cached coverage plus the smallest explicit fresh host witness.
Keep only work whose asserted property is current scheduling, contention, elapsed time, external service lifecycle, or an external mutation fresh. Each uncached task must document that reason.
Keep builds cacheable whenever their complete output identity is declared. Platform-neutral build reuse requires byte-equivalent output proof; otherwise the build remains cacheable under the narrower runtime or capability identity.
The complete task performs no workload. Its marker may remain uncached or be removed; this does not leave test execution uncached.

Question: Should one required pull-request release-candidate gate run the complete prospective merge tree, including release-shaped environment and package/baseline assembly, so post-merge publication consumes exact tree-bound evidence instead of discovering new product-test failures?

Accepted answer:

Yes.
Keep fast diff-aware jobs for feedback and run the complete candidate gate on pull requests.
Bind its attestation to the exact prospective merge tree and complete assembled artifacts.
On main, verify that evidence, classify, reconcile, and publish without rerunning the long test graph.
Under GitHub Free the check cannot prevent a merge, but it is mandatory for publication.
Refuse automatic publication for a direct, red, cancelled, or otherwise unattested main commit; recovery proceeds through a later reviewed pull request whose complete candidate passes.

Q23

Prerequisites:

Question: Which local hooks should catch failures before GitHub CI?

Accepted answer:

Run a fast cache-backed staged-diff gate at pre-commit. This needs a worktree-aware selector; the current commit-to-commit selector cannot be reused unchanged.
Run the complete cache-backed release-candidate graph at pre-push using the pinned CI runtime and canonical environment.
Keep the same repository command callable directly for diagnosis and CI parity.
Do not require the complete graph on every commit; it may still be slow on a cold cache. The pre-push gate validates the exact committed tree before it reaches GitHub.

Q24

Prerequisites:

Question: May the Devpunks organization upgrade this private repository to GitHub Team so required checks and branch protection can actually gate automatic production publication?

Rejected answer:

Do not upgrade or pay for GitHub Team.
Use only the controls available on the current GitHub Free plan.
Accept that Free cannot prevent a red pull request or direct push from reaching main in this private organization repository.
Do not make branch protection an activation prerequisite for automatic publication.
Keep publication fail-closed: the publisher requires exact successful pull-request candidate evidence for the current tree, so red, cancelled, direct, or unattested main commits perform no production mutation.
The live Free-plan repository API already exposes the existing Production environment with no protection rules. It remains usable for npm OIDC binding without implying reviewers or paid deployment gates.
Keep npm Trusted Publisher configuration as the remaining external activation prerequisite.

Shared-Understanding Confirmation

Confirmed by the user on 2026-08-10 after Q24 was replaced with the Free-plan publication-evidence boundary.
The confirmed model covers cache-by-default portable and capability-keyed verification, staged-diff pre-commit and complete pre-push gates, complete pull-request candidate attestation, semantic none/baseline/npm/mixed classification, and exact-evidence publication from main.
Stable-only channels, compatible patch ranges, simple baseline-first mixed releases, serialized idempotent recovery, Vercel-scoped baseline credentials, and npm OIDC through the existing Production environment remain accepted.
The decision frontier is closed and ready for specification compilation.

Specification Handoff Evidence

Base: origin/main at caee8be43d38bfaaaff4cc3c90cb14c8b82c245a.
Parent stack: none. The accepted repository workflow is one feature/spec branch into main.
The integration branch contains both research reports and the confirmed grill on top of that exact base.
Original immutable research refs remain retained at research/cache-release-diff-classification@7e196b2223d39e8767fb76356f7c56fb0630d966 and research/cache-release-green-main-gaps@eabdd5f7206f0aeeb3a3aaba4ff31de5dc30d1f8.
No prototype applies.

Cache and Release Classification Grill Log

On this page