forge-freeze

Freezes are immutable version snapshots (spec/format.md): an annotated Git tag, a prototype + Storybook build, immutable preview URLs, a handoff pack, and a freezes.json entry. The stakeholder PIN is not one of them — it gates hosting, so forge publish mints it (DDR-115). forge freeze does all of that — this skill's job is making sure the tag actually tells the story of what changed, not just stamping a version number.

Steps

1. Confirm this is really a freeze moment. A freeze is meant to be a coherent, reviewable slice of work — not every commit. If the user's just thinking out loud, keep talking instead of jumping to forge freeze.
2. Look at what's actually changed since the last freeze. Check freezes.json for the most recent entry's date/commit, then skim:
   • the task ledger's ## Done section for tasks closed since then.
   • the record's feedback for anything resolved (accepted → shipped, declined → recorded why).
   • decisions/ for DDRs accepted since then. Don't just list task titles back at the user — that's what git log is for. Draft a short "what shipped and why it matters" summary a stakeholder (not another engineer) would actually read.
3. Pick the tag. A short, sequential, human name — alpha, beta, mvp, v0.3 — not a date or a commit hash. Ask the user if it's not obvious from context.
4. Make sure the working tree is clean. forge freeze refuses to run otherwise (freezes are immutable, so nothing can be silently left out). If the feedback, tasks, or decisions changes from earlier in this session (or anyone else's) aren't committed yet, commit them first — don't freeze over uncommitted record changes.
5. Run it:

   forge freeze <tag> --message "<the summary from step 2>"

   Freeze produces the artifact; it does not host it. The build is a static directory, so any host can serve it — that is how a stakeholder sees it without Forge Cloud. If the user has a Forge Cloud account (a closed beta, invited accounts only; forge whoami says), follow with forge publish <tag>, which prints the review URL. Don't suggest signing up: there is no open sign-up yet. Publish sends the build and, beside it, the record concepts whose audience is stakeholders as they stood at the tag — it prints how many crossed and how many stayed home. Nothing owner-only leaves the repo.

6. Report back exactly what the command printed: the review URL if you published, the PIN that publish printed with it, and where the handoff pack landed. Don't paraphrase the URLs — copy them verbatim so the user can hand them off directly.

   If you published, say plainly that the PIN is not saved in the repo. It is shown once, and after that it lives only in Cloud, at app.useforge.design/prototypes, where it can also be changed. That is deliberate: it used to be committed to freezes.json, which put every review gate into every clone of the repository (DDR-115).

   Two things the freeze does quietly that are worth mentioning when they apply:

   • Scenarios ride along. Any SCENARIO-### in the record is emitted into the build, so the reviewer gets a scenario selector, and a scenario with ## Flow steps turns the review into a guided pass — their comments record which step they were on. If the record has no scenarios, review is unguided; if that matters for this release, say so rather than letting the user find out from a stakeholder.
   • Old share links update themselves. Comments whose feedback shipped in this release now read "addressed in <tag>" on the preview the stakeholder already has. If the command reported any, tell the user — it is often worth a note to the person who raised them.
7. Run forge doctor and fix anything it reports.

The feature log

forge freeze writes design/feature-log.md: one section per freeze, each listing what reached Done since the freeze before it. "Closed since" is read from Git by comparing the task ledger at consecutive tags — a task carries opened and a status, never a closed date — so the whole file is regenerated from the tags each freeze rather than appended to.

It carries a generated: key and a "do not edit" line for anyone reading it raw. Both are load-bearing: forge doctor fails a derived file that has been hand-edited.