ss-update

# StyleSeed update
## Registry-first artifact boundary

When `.styleseed/project.json` and `.styleseed/artifacts/index.json` exist, resolve the requested artifact ID first, then read only `.styleseed/bundles/<artifact-id>.md` and `.styleseed/manifests/<artifact-id>.json`. Never fall back to the global legacy bundle for a registry project. Legacy projects may use `.styleseed/effective-rules.md` only when no registry exists.

Update the **engine payload**, not the user's product UI. A release version describes a published
line; `engineRevision` identifies the exact maintained rules, skills, entry docs, and palette
engine. Two installs with the same release version are not proven equal until their revisions
match.

The checker verifies the payload for the active install channel. A repository/plugin checkout
uses the full `core` inventory; a project-local Agent Skills install uses the executable `skills`
inventory. The published endpoint must expose both the engine `revision` and, for a skills-only
install, `skillsRevision`. The project manifest continues to record the engine revision that
compiled its method bundle.

## When not to use

- First installation → `/ss-setup` or `$ss-setup`.
- One new screen or component → `/ss-build`, `/ss-page`, or `/ss-component`.
- A redesign of old UI → update first, then offer the optional retrofit step below.
- A heavily forked StyleSeed payload → stop after the dry-run report and request a manual diff.

## Ownership boundary

StyleSeed owns installed `ss-*` skill payloads and compiled `.styleseed/effective-rules.md`.
The project owns `STYLESEED.md`, application code, components, tokens, assets, and any existing
`AGENTS.md`, `CLAUDE.md`, or Cursor instructions. Never overwrite project-owned files merely to
update StyleSeed.

An update may change design-method behavior, especially across major versions. It is reversible
through the user's version control, but it is not correct to promise that every update is
additive or non-breaking.

## Step 1 — Read-only revision check

From the user's project root, run the bundled checker by its installed path:

```bash
node <installed-ss-update>/scripts/check-update.mjs --project-root . --json
```

Interpret the result exactly:

- `current` — installed and published revisions match; stop unless the user explicitly wants a
  reinstall.
- `update-available` — refresh the installed payload even when the semantic versions match.
- `project-bundle-stale` — skills are current; skip reinstall and re-resolve the project.
- `legacy-skill-conflict` — the retired standalone seven-category reviewer remains beside the
  canonical skills. Show its path and hash; remove it only after confirming it is not a
  project-modified skill.
- `remote-revision-unavailable` — version-only evidence cannot prove currency. Report the
  boundary and do not say “up to date.”

For registry projects, also read the sorted `artifacts` array. Its status is computed from the
current artifact contract, manifest, declared output bytes, and installed catalog every time:

- `current` — method, validation contract, and output bytes still match;
- `corrupt` — a declared bundle/palette is missing or its bytes do not match;
- `method-changed` — recompile, then rerun every implementation/render evidence gate;
- `validation-changed` — recompile only when reported, and rerun the gates marked `stale`;
- `metadata-changed` — recompile for the installed engine metadata; unchanged visual evidence is
  not invalidated by metadata alone;
- `legacy` — migrate the artifact before claiming artifact-level currency.

`changedInputs` names project-owned inputs whose current normalized bytes differ from the manifest.
When prior validation details are unavailable, the checker fails closed by marking every potentially
affected gate stale; it does not invent a precise field-level history from a digest.

Also inspect `git status --short`. Do not modify files during this step.

## Step 2 — Report the update boundary

Before changing anything, report:

```text
StyleSeed update report
- Installed: <version> @ <revision>
- Installed payload: <core|skills> @ <distribution revision>
- Published: <version> @ <revision>
- Project bundle: <version/revision or not resolved>
- Project worktree: clean | has existing changes
- Will refresh: canonical ss-* skill payloads
- Will preserve: STYLESEED.md, app code, components, tokens, assets, project instructions
- Requires review: compiled rule-bundle diff and any copied legacy engine docs
```

If the worktree has unrelated changes, preserve them. Recommend a commit or backup before a
method update, but do not use destructive reset/checkout commands as an update strategy.

## Step 3 — Refresh through the original install channel

Use the same channel that installed StyleSeed:

- Agent Skills CLI installation: run `npx skills add bitjaru/styleseed` and select the same
  project/provider scope. The repository exposes exactly the canonical 23 `ss-*` skills.
- Claude/plugin or another provider marketplace: use that provider's normal update action.
- Vendored source checkout: fetch the intended tag or commit, review the diff, and update the
  canonical engine as a set. Do not mix files from two revisions.

Do not implement an update with a blind recursive copy into an existing skills directory. The
installer must reconcile the managed payload; project-owned files stay outside that operation.

If this skill was invoked only to inspect availability, stop before the external refresh and
present the report.

## Step 4 — Prove the installed revision

Run the new checker's path again. Require the installed and published `engineRevision` values to
match before describing the engine as current. A matching version string by itself is not proof.

If the installed payload still reports the old revision, stop. Do not recompile the project from
a mixed or unproven installation.

## Step 5 — Recompile the project context

For a registry project (`.styleseed/project.j