@natjswenson/press 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to the **press** skill are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-08-01
+
+### Fixed
+
+- **The propagate workflow could never fire on a release.** It triggered on
+  `push: tags: [press-v*]`, but the release tag is created by `_release.yml`
+  using the repository's `GITHUB_TOKEN`, and GitHub does not start new workflow
+  runs for events created with that token. The trigger looked correct and
+  executed exactly zero times — confirmed on the 0.4.0 release, which tagged and
+  published with no propagate run at all.
+
+  The release path now calls the workflow directly (`workflow_call` from
+  `press.yml`'s `propagate` job, `needs: release`), which runs in the same chain
+  and is not subject to that restriction. The weekly schedule and manual
+  dispatch were always unaffected.
+
+## [0.4.0] - 2026-08-01
+
+Closes the propagation gap: a pinned check can tell you a consumer is intact,
+but never that it is *current*.
+
+### Added
+
+- **`press propagate`** — re-emits every region in a consumer's checkout, bumps
+  any `@natjswenson/press@<version>` pin in its workflows, and reports what
+  moved. `--dry-run` answers "is this repo behind?"; `--json` is what CI
+  branches on.
+- **`.github/workflows/press-propagate.yml`** — runs on every `press-v*` tag and
+  weekly, opening a PR in each consumer repo whose bytes actually changed. The
+  consumer list is derived from `targets.json` (with an optional `github` field
+  where the remote name differs), so adding a consumer stays one declaration.
+  Without `PRESS_PROPAGATE_TOKEN` it reports what it would do and exits clean,
+  rather than failing a release over a missing credential.
+
+### Why
+
+Consumers pin an exact version on purpose — a mutable reference in a repo that
+auto-deploys to production is a supply-chain hole. But a pinned check passes
+forever against the version it was pinned to: `natejswenson.io` sat **two
+releases behind with entirely green CI**. Integrity and freshness are different
+questions, and only the first was being answered.
+
+So freshness is pushed from the source of truth rather than polled by each
+consumer. Two rules keep it honest:
+
+- **Content decides, not the version receipt.** A region written by 0.1.0 that
+  is still byte-correct today is current; opening a PR for it would be noise.
+- **A stale pin alone is not "behind".** It changes no shipped artifact, so it
+  is bumped quietly and never triggers a PR by itself.
+
+### Fixed
+
+- `changed` was derived by matching `/updated$/` against a status string, which
+  silently missed `"would update"` — so `--dry-run` reported "nothing to do"
+  while displaying a changed region. It is a boolean now, and a test pins that.
+
 ## [0.3.0] - 2026-08-01
 
 Font stacks become per-engine profiles. Migrating `local-fitness` measured a real
@@ -127,6 +183,8 @@ source of truth and a CI drift gate.
   rasterised cards, whose eyebrow legitimately runs at `.16em`. Scoped rather
   than waived, and caught by linting the real shipped corpus.
 
+[0.4.1]: https://github.com/natejswenson/claude-skills/releases/tag/press-v0.4.1
+[0.4.0]: https://github.com/natejswenson/claude-skills/releases/tag/press-v0.4.0
 [0.3.0]: https://github.com/natejswenson/claude-skills/releases/tag/press-v0.3.0
 [0.2.0]: https://github.com/natejswenson/claude-skills/releases/tag/press-v0.2.0
 [0.1.0]: https://github.com/natejswenson/claude-skills/releases/tag/press-v0.1.0

package/SKILL.md

@@ -2,7 +2,7 @@
 name: press
 description: The one brand system for everything produced in Claude — design tokens, the visual laws, the run-presentation contract, and the universal voice core. Use when composing or restyling any artifact (report, résumé, card, cover, PDF, HTML page, chart), when asked about brand colors, fonts, the accent law or "the PRESS look", when adding a new skill that renders anything, or when a brand value needs to change everywhere at once. Also handles "check the brand is in sync", "why do my colors differ", and onboarding a new consumer repo.
 user_invocable: true
-version: 0.3.0
+version: 0.4.1
 ---
 
 # /press — the brand system
@@ -79,6 +79,46 @@ nothing reports "all clean", which is exactly how a gate turns decorative.
 On failure it prints the diff and the exact `press emit` command that fixes it.
 Run that; do not hand-edit the region.
 
+## How a change reaches every product
+
+There are **two different questions**, and conflating them is what leaves a
+consumer silently stale.
+
+| | Question | Answered by | Runs |
+|---|---|---|---|
+| **Integrity** | does this region match the press version this repo adopted? | `press check` | inside each consumer, against a **pinned** version |
+| **Freshness** | has this repo adopted the **current** brand? | `press propagate` | from press, against a consumer's checkout |
+
+**A pinned check can never answer the second question** — it passes forever
+against the version it was pinned to. That is not a hypothetical: this skill's
+own site consumer sat two releases behind with entirely green CI.
+
+**Consumers pin on purpose.** A mutable `@latest` in a repo that auto-deploys to
+production is a supply-chain hole, and a reproducible check is the only kind
+worth gating a merge on. So freshness is **pushed from here** rather than polled
+by each consumer:
+
+```bash
+node bin/press.js propagate --repo ../budget --dry-run   # is it behind?
+node bin/press.js propagate --repo ../budget             # re-emit + bump its pin
+```
+
+`propagate` re-emits every region it resolves, bumps any
+`@natjswenson/press@<version>` pin it finds in that repo's workflows, and reports
+what moved. The caller turns that into a pull request, so nothing lands
+unreviewed — but nobody has to *remember*.
+
+Two rules keep it from becoming noise or a false negative:
+
+- **Content decides, not the version receipt.** A region written by 0.1.0 that
+  is still byte-correct under 0.3.0 is *current*. Opening a PR for it would be
+  noise.
+- **A stale pin alone is not "behind".** It changes no shipped artifact, so it
+  is bumped silently and never triggers a PR on its own.
+
+`.github/workflows/press-propagate.yml` runs this on every release and weekly,
+opening a PR in each consumer repo whose bytes actually moved.
+
 ## Changing a brand value
 
 This is the one operation that touches every product, so do it deliberately.
@@ -88,11 +128,15 @@ This is the one operation that touches every product, so do it deliberately.
 3. `node bin/press.js emit`, then run the affected skills' own test suites —
    a token change must not break anyone's baseline.
 4. Re-render one real artifact per affected medium and **look at it**.
-5. For repos outside this one, run `npx -y @natjswenson/press@latest emit
-   --repo <path>` in each. Always pin `@latest`: a bare `npx @natjswenson/press`
-   silently prefers a stale global install over the registry.
+5. Bump the version and add a `CHANGELOG.md` entry in the same change.
 
-Bump the version and add a `CHANGELOG.md` entry in the same change.
+**Repos outside this one need no manual step.** Releasing the version bump fires
+`press-propagate.yml`, which opens a PR in every consumer whose bytes actually
+moved. To see it early, dry-run against a local checkout:
+
+```bash
+node bin/press.js propagate --repo ../budget --dry-run
+```
 
 ## Onboarding a new consumer
 
@@ -108,10 +152,27 @@ Bump the version and add a `CHANGELOG.md` entry in the same change.
    | `markdown-block` | one of the brand docs, inlined into a SKILL.md |
    | `json` | raw values |
 
-3. Add an `init` anchor naming the first and last line of the hand-written block
+3. **Pick the font profile for its rendering engine.** `params.font_profile` is
+   `browser` by default. Anything going through **fontconfig — WeasyPrint above
+   all — must say `fontconfig`**, because it walks the fallback chain for real
+   and the browser chain resolves headlines to Helvetica Neue Heavy Condensed.
+   Survey the consumer's current stacks before you assume.
+4. Add an `init` anchor naming the first and last line of the hand-written block
    the region takes over, so the duplicate is **swallowed**, not left behind.
-4. `node bin/press.js emit --target <id> --init`
-5. Add a `press check` step to that repo's CI.
+5. `node bin/press.js emit --target <id> --init`
+6. Add a `press check` step to that repo's CI, **pinned to an exact version**:
+   `npx -y @natjswenson/press@0.4.0 check --repo .`. Never write a bare
+   `npx @natjswenson/press` — with no version reference at all, npx silently
+   prefers a stale global install over the registry, which cost this repo a
+   release once already. An exact pin also keeps a mutable dependency out of a
+   repo that auto-deploys to production; `propagate` bumps it for you.
+7. If its GitHub repo name differs from the `repo` field (budget lives at
+   `local-budget`), add `"github": "<name>"` so propagation can find it.
+
+**Survey before you emit.** Diff the consumer's real values against the token set
+first: adopting the site turned up a `'JetBrains Mono'` fallback and three alpha
+tints the tokens could not express, and emitting blindly would have silently
+dropped them. Widen the tokens to the union; never narrow a consumer.
 
 **Aliases are deliberate.** The résumé keeps `--sig`, the site keeps `--fg`. The
 names stay idiomatic to their medium; only the values are shared. Renaming

package/bin/press.js

@@ -16,6 +16,7 @@ import { initRegion, spliceRegion, findRegion } from '../lib/region.mjs';
 import { loadTargets, repoRoot, selectTargets, targetPath } from '../lib/targets.mjs';
 import { checkAll, EXPLAIN } from '../lib/check.mjs';
 import { lintText } from '../lib/lint.mjs';
+import { propagate } from '../lib/propagate.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
@@ -25,6 +26,7 @@ const USAGE = `press v${VERSION} — one brand, generated into every consumer.
   press emit  [--target <id>…] [--repo <path>] [--init] [--dry-run]
   press check [--target <id>…] [--repo <path>] [--json]
   press lint  <file…> [--accent-cap <n>] [--raster] [--waive <rule>…]
+  press propagate [--repo <path>] [--dry-run] [--json]
   press doctor [--repo <path>]
   press tokens [--format json|css|md]
 
@@ -65,6 +67,8 @@ function main(argv) {
       return cmdCheck({ tokens, root, values });
     case 'lint':
       return cmdLint({ tokens, files: positionals.slice(1), values });
+    case 'propagate':
+      return cmdPropagate({ tokens, root, values });
     case 'doctor':
       return cmdDoctor({ root, values });
     case 'tokens':
@@ -176,6 +180,35 @@ function cmdLint({ tokens, files, values }) {
   return findings === 0 ? 0 : 1;
 }
 
+function cmdPropagate({ tokens, root, values }) {
+  const report = propagate({
+    tokens,
+    targets: loadTargets(),
+    root,
+    version: VERSION,
+    dryRun: values['dry-run'],
+  });
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return 0;
+  }
+
+  if (report.regions.length === 0) {
+    return fail('no targets resolved under this repo — nothing to propagate');
+  }
+  table(['Target', 'File', 'Wrote by', 'Result'],
+    report.regions.map((r) => [r.id, r.path, r.wroteBy ?? '—', r.status]));
+  if (report.pins.length) {
+    table(['Workflow', 'Pinned', 'Now', 'Result'],
+      report.pins.map((p) => [p.file, p.from, p.to, p.status]));
+  }
+  process.stdout.write(report.changed
+    ? `\nThis repo is BEHIND — ${report.stale.join(', ')} changed. Commit and open a PR.\n`
+    : `\nAlready on press v${VERSION}; nothing to do.\n`);
+  return 0;
+}
+
 function cmdDoctor({ root, values }) {
   const all = loadTargets();
   const here = new Set(selectTargets(all, { root, ids: [] }).map((t) => t.id));

package/lib/propagate.mjs

@@ -0,0 +1,117 @@
+/**
+ * Propagation — how a token change reaches every product.
+ *
+ * There are two different questions, and conflating them is what leaves a
+ * consumer silently stale:
+ *
+ *   INTEGRITY  "does this region match the press version this repo adopted?"
+ *              Answered by `check`, run inside each consumer against a PINNED
+ *              version. Pinned because a mutable reference in a repo that
+ *              auto-deploys to production is a supply-chain hole, and because a
+ *              reproducible check is the only kind worth gating a merge on.
+ *
+ *   FRESHNESS  "has this repo adopted the CURRENT brand?"
+ *              Answered here, by running the newest press against a consumer's
+ *              checkout. A pinned check can never answer this — it passes
+ *              forever against the version it was pinned to, which is exactly
+ *              how natejswenson.io sat two releases behind with green CI.
+ *
+ * So freshness is pushed from the source of truth rather than polled by each
+ * consumer: press re-emits into the checkout, bumps the pin it finds, and the
+ * caller turns that into a pull request. Consumers still review and merge, so
+ * nothing lands unreviewed — but nobody has to *remember*.
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { emitBody } from './emit.mjs';
+import { findRegion, spliceRegion } from './region.mjs';
+import { selectTargets, targetPath } from './targets.mjs';
+
+/** The npm reference consumers pin in CI, e.g. `@natjswenson/press@0.3.0`. */
+const PIN_RE = /(@natjswenson\/press@)(\d+\.\d+\.\d+)/g;
+
+/**
+ * Re-emit every resolvable region in `root` and bump any pinned press version
+ * found in its workflows.
+ *
+ * Returns a summary rather than printing, so the same call serves the human
+ * table, the `--json` output a CI job branches on, and the tests.
+ */
+export function propagate({ tokens, targets, root, version, dryRun = false }) {
+  const selected = selectTargets(targets, { root, ids: [] });
+  const regions = [];
+
+  for (const target of selected) {
+    const path = targetPath(target, root);
+    const before = readFileSync(path, 'utf8');
+    const found = findRegion(before, target.region, target.syntax);
+    if (!found) {
+      regions.push({ id: target.id, path: target.path, status: 'missing' });
+      continue;
+    }
+    const body = emitBody(tokens, target.emitter, target.params ?? {});
+    const after = spliceRegion(before, target.region, target.syntax, body, version);
+    // Compare the region bodies, not whole files: the start marker carries the
+    // emitting version, so a no-op release would otherwise look like a change
+    // and open a pull request that alters nothing anyone can see.
+    const changed = found.body.replace(/\s+$/, '') !== body.replace(/\s+$/, '');
+    if (changed && !dryRun) writeFileSync(path, after, 'utf8');
+    regions.push({
+      id: target.id,
+      path: target.path,
+      // `changed` is carried as a boolean, never re-derived from the status
+      // string: matching /updated$/ silently missed "would update", so a
+      // dry run reported "nothing to do" while showing a changed region.
+      changed,
+      status: changed ? (dryRun ? 'would update' : 'updated') : 'current',
+      wroteBy: found.version,
+    });
+  }
+
+  const pins = bumpPins(root, version, dryRun);
+
+  return {
+    root,
+    version,
+    regions,
+    pins,
+    // A repo is behind if its bytes moved. A pin bump alone is not worth a pull
+    // request — it changes no shipped artifact.
+    changed: regions.some((r) => r.changed),
+    stale: regions.filter((r) => r.changed).map((r) => r.id),
+    missing: regions.filter((r) => r.status === 'missing').map((r) => r.id),
+  };
+}
+
+/**
+ * Rewrite `@natjswenson/press@X` to the running version across a repo's
+ * workflow files. The pin and the region must move together: adopting new
+ * bytes while still pinning the old version makes that repo's own `check` fail,
+ * which would be a confusing way to learn about a brand update.
+ */
+function bumpPins(root, version, dryRun) {
+  const dir = join(root, '.github', 'workflows');
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!/\.ya?ml$/.test(name)) continue;
+    const path = join(dir, name);
+    const text = readFileSync(path, 'utf8');
+    const found = [...text.matchAll(PIN_RE)].map((m) => m[2]);
+    if (found.length === 0) continue;
+    const behind = found.filter((v) => v !== version);
+    if (behind.length === 0) {
+      out.push({ file: `.github/workflows/${name}`, from: found[0], to: version, status: 'current' });
+      continue;
+    }
+    if (!dryRun) writeFileSync(path, text.replace(PIN_RE, `$1${version}`), 'utf8');
+    out.push({
+      file: `.github/workflows/${name}`,
+      from: [...new Set(behind)].join(', '),
+      to: version,
+      status: dryRun ? 'would bump' : 'bumped',
+    });
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/press",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "One brand system — tokens, laws, run presentation and voice core — generated into every consumer with a CI drift gate",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json

@@ -32,14 +32,24 @@
       "rationale": "ghostwriter's learned voice and devlog's release-note shape are personal, per-medium, and higher-signal than the universal floor. Without this precedence rule, folding voice into press would degrade both."
     },
     {
-      "id": "npx-must-pin-latest",
-      "pattern": "Always pin `@latest`",
-      "rationale": "A bare npx invocation silently prefers a stale global install over the registry. This exact failure cost this repo a release with shipflow; the same trap applies verbatim to press."
+      "id": "npx-must-carry-a-version",
+      "pattern": "Never write a bare\\s+`npx @natjswenson/press`",
+      "rationale": "A bare npx invocation with no version reference silently prefers a stale global install over the registry; this exact failure cost this repo a release with shipflow. The rule was originally 'always pin @latest'; from 0.4.0 consumers pin an EXACT version instead, because a mutable reference in a repo that auto-deploys to prod is a supply-chain hole and propagate now handles the bumping. Either form avoids the stale-global trap — a bare invocation is the thing that must never appear."
     },
     {
       "id": "look-at-the-artifact",
       "pattern": "Re-render one real artifact per affected medium and \\*\\*look at it\\*\\*",
       "rationale": "A token change is the one edit that touches every product at once, and no test asserts taste. The visual confirmation step is the only thing standing between a one-character edit and shipping it everywhere."
+    },
+    {
+      "id": "integrity-and-freshness-are-different",
+      "pattern": "pinned check can never answer",
+      "rationale": "The propagation design rests on these being separate questions: a pinned check proves the region is intact, never that it is current. natejswenson.io sat two releases behind with green CI. If this line goes, the next person 'simplifies' by dropping propagate or by unpinning consumers, and either choice reopens a real failure."
+    },
+    {
+      "id": "fontconfig-consumers-need-their-own-profile",
+      "pattern": "must say `fontconfig`",
+      "rationale": "WeasyPrint walks the fallback chain for real, so the browser-tuned stack resolved local-fitness headlines to Helvetica Neue Heavy Condensed. A new consumer onboarded without checking its engine ships that regression silently — the emitted CSS looks correct and only the rendered PDF is wrong."
     }
   ],
   "baseline": [
@@ -47,7 +57,9 @@
       "id": "pre-migration-value-snapshot",
       "kind": "golden",
       "test": "tests/baseline.test.mjs",
-      "fixtures": ["tests/fixtures/pre-migration-values.json"],
+      "fixtures": [
+        "tests/fixtures/pre-migration-values.json"
+      ],
       "update_command": "node tests/fixtures/update-pre-migration.mjs",
       "rationale": "A frozen snapshot of every brand value as it actually existed in eight files across four repos (claude-skills, budget, local-fitness, natejswenson.io) before press generated any of them. This is the migration's no-op proof: whatever press emits must still carry those values, so a future token edit that silently changes a colour a shipped product depends on goes red instead of quietly re-rendering every artifact wrong. Pinned to a real past state, never synthesised. The paired negative assertion (deleting the accent from the known set must be detected) keeps the check from passing while the comparison rots, and a min_sources floor of 7 stops the fixture from shrinking to nothing and still reporting clean."
     },

package/targets.json

@@ -244,7 +244,8 @@
       "init": {
         "replaceFrom": "^import copy$",
         "replaceTo": "^    return theme$"
-      }
+      },
+      "github": "local-budget"
     },
     {
       "id": "local-fitness",