The states and notes of pharn update that most runs never meet. Each section
is linked from the command page.
Some installed files run together: the floor checkers (pharn/floor/, every file pharn installs there,
including the .json maps the checkers read), the hooks (.claude/hooks/*.cjs / *.mjs) and the product
commands (.claude/commands/pharn-*.md, which call the floor checkers by name and flag). Upgrading part of
that set leaves two versions side by side, and a new checker that imports something an old, edited sibling
does not export fails as soon as it loads.
So when a run moves you to a new skills version without --force and any file of that set would be
skipped (modified, unrecorded, unverifiable or unreadable), update writes none of the set's
other files either. Those are reported as held. Everything outside the set (capability directories,
the trusted docs, contracts, pharn-core, the license and the features README) is still decided file by
file.
Membership is decided by path only: pharn does not read a file or follow its imports. Before the
question, and again after the run, an EXECUTABLE UNIT note names the files that blocked the set and says
how many were held:
◇ EXECUTABLE UNIT
│ The floor, the hooks and the pharn-* commands run together, so pharn
│ writes them all or none. These unit files were skipped:
│ modified pharn/floor/reconcile-baseline.mjs
│
│ So 3 other unit file(s) were not written either, and the
│ unit stays at the version you had: upgrading part of it would mix two
│ versions that may not load together.
│
│ To upgrade the unit: revert the skipped files, or run
│ `pharn update --force` (it backs them up to pharn/.backup/ first).
What follows from a hold:
- The recorded
skillsVersionis withheld, as for any skip. - When every file that blocked the unit (and every other skipped file) is one you edited (
modifiedorunrecorded), the version the run applied is recorded aspendingSkillsVersion, andpharn addinstalls at it: it writes capability directories only, which are outside the unit and were upgraded anyway. When any blocker is something else (unverifiablebecause there is no usable record store, orunreadable), nothing is recorded, andpharn addrefuses until the update can finish.pharn update --dry-runshows what blocks it. - A unit file that is missing is not put back while the unit is held. The note names such files under
"Of those, these are not on disk, so they stay missing until the hold ends". For a hook you deleted, that
means:
pharnnever touches.claude/settings.json, so the hook entry stays wired to a script that is not on disk, and that guard does not run until the hold ends.pharn statusreports the file as missing in the meantime. - A held file keeps its old record, and a file new upstream gets none. The next run decides them again.
- The run exits 0, like every skip. The note is the signal, not the exit code.
--forcenever holds. It backs up the skipped files and writes the whole set (anunreadablepath is still skipped).- At the same skills version (a run that restores a missing file, for example) nothing is held: restoring a file then puts back bytes of the version you already have.
What pharn can promise here is only that it wrote no file of the set. It cannot prove that your edited
files work together, and a file that was already identical to upstream before the run is left as it is.
Editing a /pharn-* command, including its model: or effort: line, also holds the floor and the hooks
until you revert the edit or use --force. --dry-run prints the same note, and --dry-run --json adds
plan.executableUnit (see JSON output).
When upstream stops shipping a file pharn installed (a pharn-* command, a hook, a floor checker, a
trusted doc, or one file inside a capability you still have), update leaves it on disk (see
What PHARN deletes). Such a file is an orphan: pharn.records.json says pharn wrote it,
it is no longer part of your install, and it is still there. A leftover .claude/commands/pharn-*.md is
still a live slash command, and a leftover hook or checker still runs if anything calls it, so update
names every orphan in an ORPHANED note:
Upstream no longer ships these files pharn installed. `pharn update` never
deletes them, and keeps listing each one until it is gone.
UNCHANGED — unchanged since pharn wrote it
.claude/commands/pharn-old.md
EDITED — changed since pharn wrote it — review before deleting
.dev/floor/check-old.mjs
Delete the ones you no longer need by hand (e.g. `git rm <path>`).
UNCHANGED: the file still has the exact bytespharnrecorded writing.EDITED: it changed since then. The change is yours, so look before deleting.UNREADABLE: something other than a readable regular file sits there (a directory, a symlink, an unreadable file), named with the reason.pharndoes not read through it.
Each group shows at most 20 paths, then … and N more; pharn status --json lists them all. An orphan is
never a skip: it does not withhold the version bump and does not appear in SKIPPED. This includes a root
THREAT-MODEL.md or LIMITS.md that an install from a pharn-oss older than 7.0.0 left and pharn recorded,
and the top-level copies of a former flat install; delete them by hand, or let
pharn uninstall remove them while they still equal their record. A root
memory-bank/, pharn.spec-template.md or .pharn/ is never moved, copied, deleted or mentioned; what to
do with them yourself is in Getting started.
It stays listed until you delete it. update keeps the orphan's entry in pharn.records.json (its old
hash) for as long as the file exists, so every later update, and every
pharn status, still names it. Once the file is gone, the next
update drops its entry, at the same skills version too, and the run after that is up to date again. If
upstream ships the path again later, the kept entry makes it a clean updated instead of an unrecorded
skip. A re-run pharn init keeps those entries too.
What is not listed:
- Files
pharnhas no record of. With no usable store, nothing is listed. - The files of a capability this update drops from your config: that is a membership change, named in
the
CAPABILITIESnote, and its directory is deleted (see Dropped capabilities are deleted). - Anything outside the paths an install can write (
.claude/commands/pharn-*.md,.claude/hooks/*.cjsor*.mjs, the capability directories,pharn-contracts/,pharn-core/, the floor directory, the trusted docs, the PHARN license and the featuresREADME.md), even if a hand-editedpharn.records.jsonnames it.
Every run plans, so an up-to-date run prints the ORPHANED note too. --dry-run --json lists orphans in
plan.orphans when its status is planned; an up-to-date report has plan: null, so use
pharn status --json (orphans) to list them then.
A capability can change upstream in a way your installed pharn does not understand yet: a new field value,
a directory that does not have its markdown yet, a shape from a newer release. update then skips that one
capability and says so; it does not abort:
1 upstream capability could not be read and was SKIPPED — not installed:
griller:backwards-compat (pharn/pharn-pipeline/grillers) — missing its markdown backwards-compat/backwards-compat.md.
- Nothing under that capability's directory is written.
pharnwill not copy content it could not validate. - Your
pharn.config.jsonentry is kept, reported asKEPT — pharn could not read these upstream this run. - Everything else updates normally, including the skills version, so the next
pharn addis not blocked.
pharn records the kept capability in frozenCapabilities in pharn.config.json. Every run downloads and
re-checks it, so the message repeats while the situation lasts. Once the capability can be read (upstream
finishes the change, or you upgrade with npm install -g @pharn-dev/pharn@latest), update brings its files
up to date and clears the field, but only once none of its files had to be skipped: a file of it you edited
is skipped as usual, and the capability stays listed until you resolve the edit or pass --force. If you no
longer want it, use pharn remove.
models in pharn.config.json is pharn-oss's block: the source of truth each /pharn-* command's
model: / effort: frontmatter is held to, which /pharn-ship and /pharn-loop read to pick the model
they request for the stages they route (see pharn.config.json). update decides
it with the decision table, using the block's hash where a file would use its bytes, and prints a MODELS
note for every outcome except "already identical":
| Your block | Default | With --force |
|---|---|---|
| absent | pharn-oss's is written | same |
| identical to pharn-oss's | nothing to do | same |
still what pharn wrote — its recorded hash |
replaced with pharn-oss's | same |
changed since pharn wrote it, never recorded, or no usable records file |
kept | pharn.config.json backed up, then replaced |
"What pharn wrote" is compared as pharn writes it: re-indenting the file is not an edit, but reordering
the block's keys is, so a reordered default counts as yours and is kept. The block's record lives in
pharn.records.json.
A kept block pharn-oss's rules reject (one you edited into an invalid shape, or one in the format
pharn wrote before 0.7.0: a top-level default, and model ids such as opus-4-8) stays exactly as it is,
and the MODELS note lists what the rules reject in it. To replace it, edit the block by hand, or delete the
models key so the next pharn update writes pharn-oss's (the "absent" row). --force replaces it too,
after backing up pharn.config.json, but also overwrites every other file you edited. An old-format block is
replaced without asking only when its recorded hash proves pharn wrote it; pharn does not convert it.
A kept block never holds back the skills version, unlike a skipped file: a block you tuned is a steady
state, not an unfinished upgrade. If your values differ from the installed commands' frontmatter,
node pharn/floor/check-model-config.mjs agreement lists where (nothing runs it automatically). Editing the
frontmatter of a /pharn-* command is a different edit: that file becomes modified, so update skips it
and does withhold the skills-version bump. Editing only the block causes no file drift, and a re-run
pharn init resets it (copying the previous pharn.config.json to pharn/.backup/ first).
If pharn-oss ships no block, yours is left alone, and what its rules reject in it is listed. If pharn-oss
ships one this pharn cannot accept (pharn-oss's rules can move ahead of the copy of them in your pharn),
the block is not applied, the reasons are listed, and upgrading pharn fixes it.
When your skillsVersion already equals upstream's, update still downloads and plans, so a missing file
is restored like on any other run: a capability directory or a recorded file that is gone, or a surface a
newer pharn release installs that your install never had (pharn/pharn-core/, say). Until then
pharn status reports such files as missing and pharn status --strict exits 1.
The decision table always restores a missing file, so your edits elsewhere are kept and no --force is
needed. --dry-run shows it under WOULD WRITE — restored, and --dry-run --json reports status
planned. The next update answers Up to date.
The review lens agent, .claude/agents/pharn-review-lens.md (shipped by pharn-oss from skills version 6.64.0
on; /pharn-review runs each lens in it, and without it each lens runs as a general-purpose agent with more
tools), is restored the same way, recorded, and kept as modified once you edit it. A .claude/agents that
is a symbolic link is never written through.
A path that goes through a symbolic link is never followed and is not restored, and neither is a path
blocked by a file where a directory should be: the run skips it (Nothing to change. when that is all it
finds), and pharn status reports it. A capability you removed with
pharn remove is restored too when your archetypes still select it (see
Removing an auto-selected capability).
pharn.records.json records the skillsVersion and commit of the pharn.config.json
it was written with. pharn add and pharn update write the store first and the config second, so a run
interrupted between the two (a crash, a full disk, Ctrl-C) leaves a store stamped for a state the config
never reached.
update uses such a store as it is: a file whose current hash equals its recorded hash holds bytes pharn
wrote, whatever version the store was written for. At the same skills version the run rewrites the store
with the config's stamp and changes nothing else, and on the next upstream release every file you did not
edit upgrades, every file you edited is skipped as modified, and no --force is needed. The two edge cases
of trusting the hash alone are in The stamp is not a gate.
A store that is absent or unreadable (invalid JSON, an unknown schemaVersion) is not used: every
present file that differs from upstream is skipped as unverifiable, and the run names the reason. pharn
cannot tell your edits from upstream's changes, and will not guess. Missing files are still restored, and
every file that matches upstream is recorded again, so a plain update writes a new store over the
unreadable one (copy it aside first if you want to repair it by hand). Resolve the rest once, either way:
pharn update --force: overwrite them, keeping a backup of the current bytes; or- inspect the listed files first (
pharn statusshows the same set), revert what you did not intend to keep, and re-runpharn update.
Either path writes a full record store. The record of a .claude/settings.json that init created cannot
be rebuilt this way: update never writes that file.
The legacy flat layout (PHARN's files at the project root: "layout": "flat" in pharn.config.json, or no
layout key) is no longer supported (support policy).
update (and --dry-run, --json) exits 1 on such a config before it downloads anything, with one message:
re-run pharn init. init reinstalls at the pharn/ layout and keeps the capabilities you added with
pharn add (init). It never moves or deletes the old top-level copies: the ones
pharn recorded stay listed under ORPHANED until you delete them. A fetched pharn-oss in
the flat layout ships no pharn-install.json, so the fetch refuses it and nothing is written.
Every product surface update installs is optional on the way in, as for
init: a fetched tree that ships nothing for one
(the commands, the hooks, a trusted doc, pharn's LICENSE copy, features/README.md, or the contracts,
pharn-core or floor dir) is still applied. A run that plans (the real one and --dry-run alike) names
each such surface in a NOT SHIPPED note, by path and kind, with the same wording as init. It is
reported, never a skip, so it does not withhold the skillsVersion bump. Every run plans, so an
up-to-date run names it too; pharn status names it on every run and fails
--strict while it lasts. Hooks are installed as .cjs or .mjs files (never *.test.cjs /
*.test.mjs); an .mjs hook's name is held to the same filename allowlist as a .cjs one, so a name
outside it refuses the run.
When your install recorded a root features/README.md (the product-loop boundary contract) and the fetched
pharn-oss ships it at pharn/features/README.md, update installs the new copy and says the root copy is
left behind and no longer managed by pharn (the dry run says it would be). Delete the root copy by hand
once nothing you keep refers to it. --dry-run --json reports this as plan.featuresReadmeRelocation.
Like init, every applied update makes sure your root .gitignore covers
pharn/.run/ (PHARN's runtime scratch) and pharn/.backup/ (pharn's backups), appending only the missing
lines: created if absent, your bytes kept exactly, CRLF kept, equivalent spellings and your own negations
respected, never written through a symlink. It runs after the config write, under the lock, and prints
Added … to .gitignore (or Created .gitignore with …); a refusal or a failed write is a warning naming the
lines, never a failed update.
At the same skills version too, a .gitignore missing either line makes the plan add it, and the following
run is up to date. A .gitignore pharn cannot write (a symlink, a directory, unreadable) is a warning, and
the run is otherwise up to date. One residual: a regular file whose write keeps failing (no permission) asks
and fails to write on every run, each with its warning. --dry-run prints .gitignore: would add …, and
--dry-run --json carries plan.gitignore.
In a project that uses Prettier, every applied update makes sure the root .prettierignore covers the
files it records writing, the same way init does: the same
detection, the same derived lines (including /pharn/features/, /pharn.config.json and
/pharn.records.json), the same append-only rules. It runs after .gitignore, under the lock, and prints
Added N paths to .prettierignore … (or Created .prettierignore with …); a refusal or a failed write is a
warning listing the lines, never a failed update.
At the same skills version too, a .prettierignore that does not cover the files the run records makes the
plan add the lines (for a project that adopted Prettier later, say), and the following run is up to date. A
file pharn cannot write is a warning; a write that keeps failing asks and fails on every run. If you
already ran prettier --write over pharn's files, they now read as changed: add the lines (or let update
add them), then pharn update --force puts pharn-oss's bytes back, backing your copies up first.
--dry-run prints .prettierignore: would add …, and --dry-run --json carries plan.prettierignore.
.claude/settings.json, your Claude Code configuration.initwrites it only when absent;updatenever touches it (not even with--force: it is not in the install manifest). Wheninitcreated it,updatekeeps the hashinitrecorded for it inpharn.records.jsonwhile the file exists, souninstallcan still remove it unchanged; a deleted file is not put back, and its record is dropped by the next update that has work to do.- The
HOOKSnote.updatecompares the hooks of.claude/settings.jsonand.claude/settings.local.jsonwith the fetched upstream ones, and names every hook upstream wires that neither file does. Matching is textual, so an equivalent hook you wrote differently is listed too. Each line is the hook as JSON. A hook whose script you already wire in another spelling (same event and matcher) is listed underREPLACE, with your current line, so you swap it rather than add a second one; the rest are listed underADD. The note also names hooks wired only insettings.local.json, which run for you but not for your teammates. See status for the full rules. pharn/CONSTITUTION.mdis protected like every other manifest path: if you have edited it, it is amodifiedskip by default.--forceoverwrites it too, after copying the current bytes topharn/.backup/.
update writes the new contents to a temporary file beside the destination and renames it into place, so it
never writes into the existing file. A hard link (a second name for the same file, which looks like an
ordinary file) therefore keeps its other name's contents: only the name inside your project gets the new
bytes. The file keeps upstream's permissions, and an installed file you made read-only is replaced like any
other: what update needs is write permission on its folder.