Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ Releases 0.4.0 and older are in [CHANGELOG-ARCHIVE.md](CHANGELOG-ARCHIVE.md).
- **`pharn --help` no longer says each option belongs to one command.** `--json`, `--yes`, `--ref` and `--dry-run` are taken by several, as the lines below the header already showed. The header now reads "Options (each names the commands that take it; any other command refuses it):".
- **`pharn status --help` now names every condition `--strict` fails on.** The `--strict` line said "exit 1 on any outdated/modified/missing file"; it now reads "exit 1 on an outdated install, a modified, missing or unreadable file, a surface upstream no longer ships, or an unwired hook (under --no-drift, only outdated is checked)", on both `pharn --help` and `pharn status --help`. What `--strict` checks is unchanged. The one full list, including what is never a `--strict` input (orphans, the `PRETTIER`, `NODE` and `MODELS` notes, a hook wired only in `settings.local.json`), is the new "Strict conditions" section of `docs/commands/status.md`, and `docs/README.md`, the troubleshooting exit-code table, the `status --json` summary and the JSON output reference link to it.

### Fixed

- **The `ORPHANED` note no longer says "pharn never deletes them".** `pharn uninstall` deletes an orphan that still equals its record, so `pharn update` and `pharn status` now print "`pharn update` never deletes them" instead. Every delete a `pharn` command makes, the check behind each, and what is never deleted are now listed on one page, [What PHARN deletes](docs/reference/deletes.md), which the command pages link to.

## [0.21.0] — 2026-11-17

### Changed
Expand Down
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,8 @@ deletes or mentions a root `memory-bank/` or `pharn.spec-template.md` (nothing
proves they are PHARN's): move them yourself to `pharn/memory-bank/` and
`pharn/spec-template.md` (`git mv`), or merge by hand when the `pharn/` copy
already exists — see
[update](docs/commands/update.md#the-root-footprint-migration).
[update](docs/commands/update.md#the-root-footprint-migration) and
[What PHARN deletes](docs/reference/deletes.md).

**Two version numbers, on purpose.** The npm package `@pharn-dev/pharn` carries
the installer's version. The content it installs carries its own,
Expand Down Expand Up @@ -306,7 +307,7 @@ Two commands sit outside the pipeline:
| `pharn update` | Re-fetch and apply the latest PHARN content using drift-safe per-file decisions. `--force` overwrites files you changed; `--yes`/`-y` skips the confirmation prompt; `--dry-run` prints what it would do and writes nothing (add `--json` for the plan as one machine-readable object, and `--compact` to leave the unchanged files out of it). |
| `pharn list` | Show installed archetypes and capabilities. Use `--json` for machine-readable output. |
| `pharn status` | Read-only version and drift report. Use `--strict` to make drift fail CI, `--no-drift` to skip byte comparison, or `--json` for one machine-readable report. |
| `pharn uninstall` | Remove PHARN: deletes only the files `pharn` recorded and you did not change, then `pharn.records.json` and `pharn.config.json` (backed up first). Never touches `.claude/settings.json` or `pharn/.backup/`. `--yes`/`-y` skips the confirmation prompt. |
| `pharn uninstall` | Remove PHARN: deletes only the files `pharn` recorded and you did not change, then `pharn.records.json` and `pharn.config.json` (backed up first). Never touches `pharn/.backup/` or a `.claude/settings.json` it did not create. `--yes`/`-y` skips the confirmation prompt. |
| `pharn --help` | Show every command, option and environment variable. `pharn <command> --help` shows one command and only the options it takes. |
| `pharn --version` | Show the installed CLI version. |

Expand Down Expand Up @@ -369,11 +370,12 @@ PHARN is intentionally conservative about writes:
and refuses the whole install — writing nothing — when a destination path
crosses a symlinked directory.
- `update` uses `pharn.records.json` to skip files it cannot prove are
untouched. The only thing it deletes is the directory of a capability it
untouched. In your project it deletes only the directory of a capability it
drops from `pharn.config.json` (PHARN runs whatever capability directories
are on disk), after backing up any file in it that `pharn` cannot prove it
wrote; it never touches `.claude/settings.json`. A re-run `init` does the
same, after listing those directories in its prompt.
same, after listing those directories in its prompt. Every delete, and what
is never deleted: [What PHARN deletes](docs/reference/deletes.md).
- `update --force` backs up overwritten files under `pharn/.backup/<timestamp>/`
before writing. `add` does the same for any destination file that differs from
upstream, and refuses the whole install — writing nothing — when a destination
Expand Down Expand Up @@ -441,7 +443,9 @@ PHARN is intentionally scoped:
activities a structured record and repeatable workflow.
- `status` reports modified, missing, and unreadable PHARN-owned paths, and
the files upstream stopped shipping that are still in your project
(orphans). Nothing deletes an orphan; that is yours to do by hand.
(orphans). `update` never deletes an orphan; delete it by hand
(`pharn uninstall` removes the unchanged ones — see
[What PHARN deletes](docs/reference/deletes.md)).
- **Supported installs: the current minor and the previous one.** v0.20.x
works with installs made by 0.19.x or 0.20.x; re-run `pharn init` on an older
install, and it keeps the capabilities you added.
Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ The CLI version (`pharn --version`) and the content version it installs (`skills
- [pharn.config.json](reference/pharn-config.md) — config file schema and overwrite behavior
- [pharn.records.json](reference/pharn-records.md) — the per-file install hashes `pharn update` compares against
- [JSON output](reference/json-output.md) — the `--json` reports of `init`, `update`, `status` and `list`: keys, stability rule, real examples
- [What PHARN deletes](reference/deletes.md) — every path a `pharn` command deletes, the check behind each, and what is never deleted
- [Support policy](support-policy.md) — which installs and `pharn` versions are supported, and what is being retired when

## Other
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,9 +239,9 @@ prompt was open (a file now byte-identical to upstream is not a change), then ap
- **Executable unit** (`lib/executable-unit.ts`): floor files, hooks and product commands are written all-or-nothing.
One skip holds the rest (`held`), so the floor never mixes two versions.
- **Deletes**: only the directory of a capability dropped from the config, because PHARN enumerates capabilities from
disk. Nothing else is deleted.
disk. Nothing else is deleted ([the full list](reference/deletes.md)).
- **Orphans** (`lib/orphans.ts`): a record key outside the new manifest that is still on disk is listed and keeps its
record. It is never deleted.
record. `update` never deletes it.
- **Every run plans**: there is no same-version shortcut. `update` downloads and plans at the recorded version too, so
a missing file, a pending ignore-file line, an old `models` block, a channel switch or a frozen
capability is handled by the one planner. "Up to date" is a plan that changes nothing (`changesNothing`); only the
Expand Down
3 changes: 2 additions & 1 deletion docs/commands/init.md
Original file line number Diff line number Diff line change
Expand Up @@ -431,7 +431,8 @@ not install again: one you added by hand that upstream no longer ships, an autom
your archetypes no longer select, and a legacy entry (written before `source` existed) they no longer
select. Each is **named** before the summary. PHARN's commands run every capability **directory** on
disk, not what the config lists, so `init` also **deletes that directory** — the same treatment
[`pharn update`](update.md#dropped-capabilities-are-deleted) gives the capabilities it drops:
[`pharn update`](update.md#dropped-capabilities-are-deleted) gives the capabilities it drops (every
delete `pharn` makes is listed in [What PHARN deletes](../reference/deletes.md)):

- **Listed first.** The overwrite prompt lists each directory under "will be DELETED", with how many of
its files would be backed up, and asks (default No) even when nothing would be overwritten. Declining
Expand Down
3 changes: 2 additions & 1 deletion docs/commands/remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ Remove a single installed **capability** — a griller or a lens — from an exi
`pharn.config.json`). The inverse of [`add`](add.md): it deletes exactly that capability's directory and
drops its entry from `pharn.config.json`. Any file in that directory that `pharn` cannot prove it wrote
unchanged is copied to `pharn/.backup/<timestamp>/` first — see
[What is backed up before the delete](#what-is-backed-up-before-the-delete).
[What is backed up before the delete](#what-is-backed-up-before-the-delete). Every delete `pharn` makes
is listed in [What PHARN deletes](../reference/deletes.md).

```bash
pharn remove <name> # e.g. pharn remove a11y
Expand Down
9 changes: 5 additions & 4 deletions docs/commands/status.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,17 +123,18 @@ its drift section compares against the older source.
On the drift path, `status` also lists the files `pharn` recorded writing that upstream no longer
ships but that are still in your project — the same `ORPHANED` note, grouped `UNCHANGED` / `EDITED` /
`UNREADABLE`, that `pharn update` prints (see [update](update.md#orphaned-files) for what each group
means and what is never listed). `pharn update` never deletes them; delete the ones you no longer need
by hand.
means and what is never listed). `pharn update` never deletes them
([What PHARN deletes](../reference/deletes.md)); delete the ones you no longer need by hand.

It needs a usable [`pharn.records.json`](../reference/pharn-records.md) — present and valid (its
`skillsVersion`/`commit` stamp does not matter). Without one, nothing is listed. A root
`THREAT-MODEL.md` or `LIMITS.md` an install from a pharn-oss before 7.0.0 left, and the old top-level
copies of a `flat` install after a re-run `pharn init`, are listed here like any other leftover.

Orphans are **not** a `--strict` input. `--strict` asks whether your install is current and intact. An
orphan is a leftover file beside it, and no `pharn` command can clear one — `update` never deletes — so
a red CI would wait on a manual delete for a file that changes nothing about the install.
orphan is a leftover file beside it that `update` never deletes (see
[What PHARN deletes](../reference/deletes.md)), so a red CI would wait on a manual delete for a file
that changes nothing about the install.

## Prettier

Expand Down
1 change: 1 addition & 0 deletions docs/commands/uninstall.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ pharn uninstall --yes # no prompt — for scripts and CI (-y works too)
```

It needs **no network and no clone**: the proof is local — [`pharn.records.json`](../reference/pharn-records.md).
What every other command deletes is listed in [What PHARN deletes](../reference/deletes.md).

## What is deleted

Expand Down
15 changes: 8 additions & 7 deletions docs/commands/update.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,9 +223,10 @@ inside the project lock, the way [`pharn remove`](remove.md) does:
`pharn update --dry-run` lists the same directories under `WOULD DELETE` (and
`plan.capabilities.removals` under `--json`) without asking.

This is the **only** thing `update` deletes. It never deletes a file upstream stops shipping inside a
capability it keeps, a tree left behind by a layout change, or anything else, and it never touches
`.claude/settings.json`. Directories that an older `pharn` left behind when it dropped a capability
Apart from its own lock and download, that directory is all `update` deletes: not a file upstream stops
shipping inside a capability it keeps, not the old top-level copies of a `flat` install, and never
`.claude/settings.json`. Every delete `pharn` makes, and what it never deletes, is listed in
[What PHARN deletes](../reference/deletes.md). Directories that an older `pharn` left behind when it dropped a capability
(it removed only the config entry) have no config entry, so `update` cannot find
them: `pharn list` does not show them, but PHARN still runs them. Delete them by hand. A re-run
[`pharn init`](init.md#dropped-capabilities-are-deleted) deletes the directories of the capabilities it
Expand Down Expand Up @@ -403,15 +404,15 @@ until you revert the edit or use `--force`.
## Orphaned files

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: the only thing
it deletes is a dropped capability's directory. Such a file is an **orphan**: `pharn.records.json` says `pharn` wrote it, it is no longer
trusted doc, or one file inside a capability you still have — `update` leaves it on disk (see
[What PHARN deletes](../reference/deletes.md)). 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:

```text
Upstream no longer ships these files pharn installed. pharn never deletes
them, and keeps listing each one until it is gone.
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
Expand Down
Loading
Loading