From 59fbf473f63d0843de50f0e7476b9b1ded295187 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 14:33:46 +0100 Subject: [PATCH] docs: trim update.md, troubleshooting and README; rare update states move to a reference page (C4.6, CORE-179) update.md 901 -> 349 lines, troubleshooting.md 972 -> 448, README.md 508 -> 246. The rare `pharn update` states move, headings unchanged, to the new docs/reference/update-advanced.md; the stale-lock rules to the new docs/reference/project-lock.md. Troubleshooting now opens with the exit-code table (130/143 on an interrupt added) and an index of the common problems. Detection rules live only in init.md "3. Detect archetypes", the install locations only in getting-started "What you get". Version history, text whose behaviour no longer exists (the root-footprint migration, the pre-0.4.0 first update, the post-confirm re-plan) and src file/function names are gone from the user docs. CHANGELOG: link targets only. Co-Authored-By: Claude Opus 5.5 --- .dev/features/core-179-trim-docs/GRILL.md | 70 ++ .dev/features/core-179-trim-docs/PLAN.md | 82 ++ .../features/core-179-trim-docs/REGRESSION.md | 16 + .dev/features/core-179-trim-docs/REVIEW.md | 50 + .dev/features/core-179-trim-docs/SHIP.md | 13 + .dev/features/core-179-trim-docs/VERIFY.md | 25 + .../core-179-trim-docs/regression-report.json | 41 + .../core-179-trim-docs/verify-report.json | 20 + CHANGELOG.md | 12 +- README.md | 525 +++------ docs/README.md | 2 + docs/commands/add.md | 2 +- docs/commands/init.md | 13 +- docs/commands/remove.md | 5 +- docs/commands/status.md | 4 +- docs/commands/update.md | 950 ++++----------- docs/getting-started.md | 69 +- docs/reference/deletes.md | 4 +- docs/reference/json-output.md | 2 +- docs/reference/pharn-config.md | 10 +- docs/reference/pharn-records.md | 10 +- docs/reference/project-lock.md | 90 ++ docs/reference/update-advanced.md | 317 +++++ docs/support-policy.md | 2 +- docs/troubleshooting.md | 1048 +++++------------ 25 files changed, 1391 insertions(+), 1991 deletions(-) create mode 100644 .dev/features/core-179-trim-docs/GRILL.md create mode 100644 .dev/features/core-179-trim-docs/PLAN.md create mode 100644 .dev/features/core-179-trim-docs/REGRESSION.md create mode 100644 .dev/features/core-179-trim-docs/REVIEW.md create mode 100644 .dev/features/core-179-trim-docs/SHIP.md create mode 100644 .dev/features/core-179-trim-docs/VERIFY.md create mode 100644 .dev/features/core-179-trim-docs/regression-report.json create mode 100644 .dev/features/core-179-trim-docs/verify-report.json create mode 100644 docs/reference/project-lock.md create mode 100644 docs/reference/update-advanced.md diff --git a/.dev/features/core-179-trim-docs/GRILL.md b/.dev/features/core-179-trim-docs/GRILL.md new file mode 100644 index 00000000..71bc172c --- /dev/null +++ b/.dev/features/core-179-trim-docs/GRILL.md @@ -0,0 +1,70 @@ +# GRILL — core-179-trim-docs (C4.6, CORE-179) + +Plan: `.dev/features/core-179-trim-docs/PLAN.md`. Spec-hash check: `sha256(ARCHITECTURE.md)` = +`bca940a5ad247c120e6d8a3acba119d0d8df51dca275964d0e54c48d729d3c4e`, equal to the plan's `spec_content_hash` (no drift). +Registered grillers: 0 (`node .dev/floor/count-grillers.mjs .` → `{"registered":0,"grillers":[]}`), so only the inline axes ran. + +## Findings + +### P0 / P1: guarantee audit and checks + +```yaml +- type: FINDING + rule_id: "P0" + severity: important + file: ".dev/features/core-179-trim-docs/PLAN.md:58" + problem: "The src-name check matches `.ts`/`.js` basenames and exported identifiers, but not a markdown link into `src/` that names a directory or a file without its extension, so a `](../../src/lib/)` link would pass." + evidence: "srcnames-grep.sh (scratchpad) → no src file path / basename and no exported function or const name" +- type: FINDING + rule_id: "P1" + severity: minor + file: ".dev/features/core-179-trim-docs/PLAN.md:59" + problem: "Moving sections from docs/commands/ to docs/reference/ changes every relative link inside them (`../reference/x.md` becomes `x.md`, `status.md` becomes `../commands/status.md`). The anchor checker catches this only if it is run after the move and before the commit." + evidence: "check-anchors.mjs (scratchpad) → 0 broken relative links / anchors" +``` + +### P4: docs cite code + +```yaml +- type: FINDING + rule_id: "P4" + severity: important + file: ".dev/features/core-179-trim-docs/PLAN.md:27" + problem: "Rewritten sentences in the Behavior steps and the troubleshooting index re-state flags and messages. Each one has to be re-checked against src (cli-args OPTIONS, the message strings), not copied from the old text, because the old text predates #412 in places." + evidence: "Behavior in 6 steps (Node check, lock, config, resolve source, download + plan, nothing-to-change, confirm, apply" +- type: FINDING + rule_id: "P4" + severity: minor + file: ".dev/features/core-179-trim-docs/PLAN.md:30" + problem: "The `130`/`143` exit-code row should name what the run prints (that the project may be partially updated) and that the lock is released, both of which the lock section already says. It should not claim a cleanup the code does not do." + evidence: "adds `130` SIGINT / `143` SIGTERM on an interrupted run, per `fatal-signal.ts`" +``` + +### P7: honest scope + +```yaml +- type: FINDING + rule_id: "P7" + severity: minor + file: ".dev/features/core-179-trim-docs/PLAN.md:31" + problem: "Cutting the pharn-oss triage/supervise version history from README is upstream feature history, not CLI history. It is not lost only because getting-started's 'After init' keeps that paragraph, and the ledger should say so." + evidence: "Day-to-day workflow (stage table + 3 lines, pharn-oss version history → link upstream)" +- type: FINDING + rule_id: "P7" + severity: minor + file: ".dev/features/core-179-trim-docs/PLAN.md:41" + problem: "Repointing links in released CHANGELOG entries is outside the ticket's file list, so keep it strictly to link targets. The pre-existing broken support-policy anchor is not this ticket's to fix (no edit to entry text)." + evidence: "CHANGELOG.md — repoint the released entries' links to moved/deleted update.md sections" +``` + +No P2 (no untrusted input), P3 (no code) or P5 (no branch) findings. + +## Summary + +The plan is a docs-only move-and-trim. Its weak spots are mechanical: links inside moved sections, a +src-link pattern the grep script misses, and re-stated flags and messages that have to be re-checked +against src rather than copied. All three can be checked with the scripts the plan already names, provided the +src-link pattern is added to the grep and the anchor check runs after the move. The "no content lost" +claim stays advisory, carried by the ledger, and the plan labels it that way. + +ADVISORY VERDICT: 6 concerns raised (0 blocking-severity, 2 important, 4 minor), for the human to weigh before /pharn-dev-build. diff --git a/.dev/features/core-179-trim-docs/PLAN.md b/.dev/features/core-179-trim-docs/PLAN.md new file mode 100644 index 00000000..0d817c74 --- /dev/null +++ b/.dev/features/core-179-trim-docs/PLAN.md @@ -0,0 +1,82 @@ +# PLAN — C4.6 (CORE-179): `update.md` to about 300 lines; troubleshooting leads with exit codes + +- spec_content_hash: bca940a5ad247c120e6d8a3acba119d0d8df51dca275964d0e54c48d729d3c4e # fix #4 (ARCHITECTURE.md) +- increment: Docs-only. Cut `docs/commands/update.md` (901 lines) to ≤ 350, `docs/troubleshooting.md` (972) to ≤ 450 and `README.md` (508) to ≤ 250 by moving the rare `update` states to a new `docs/reference/update-advanced.md`, deleting version history and text whose behaviour no longer exists, single-sourcing the detection rules and the install-location table, and removing every src file / function name from the user docs. +- layer(s): user docs (`README.md`, `docs/**`), plus link targets in `CHANGELOG.md`. No `src/`, no `tests/`, no protected file. +- constitution_refs: [P4, P6, P7] + +## Discovery (live state, origin/main a844f7a7) + +- Sizes: update.md 901, troubleshooting.md 972, README.md 508, getting-started.md 141. +- **No test reads a user doc** (`grep` for `docs/`, `README`, `troubleshooting`, `update.md` in `tests/` hits only fixture paths and unrelated strings). So no assertion needs rewriting; no test file or `it`/`describe` is touched. +- Version history is already in `CHANGELOG.md` / `CHANGELOG-ARCHIVE.md` for every passage to be cut (checked: the stderr-through-0.3.2 fix, colour before 0.13.0, the executable unit before 0.18.0, the Node 20.13 floor before 0.8.0, the constitution overwrite before 0.4.0, degit proxy and cache, argv "used to" behaviour, the stamp-as-gate, `updatedAt` before 0.20.0, `.gitignore` 0.16.0 / `.prettierignore` 0.17.0). Nothing is added to the CHANGELOG. +- **Dead text** (behaviour no longer exists on main; deleted, not moved): + 1. update.md "The root-footprint migration" (removed by #412): the `ROOT MIGRATION` note, the deletion of root `THREAT-MODEL.md`/`LIMITS.md`, the move hints. What is still true (a root copy pharn recorded is an `ORPHANED` file; `plan.rootMigration` is always `null`, already in json-output.md) is kept as one sentence in the orphans section. + 2. update.md "First update after upgrading" and the `unverifiable` label's "every install created before 0.4.0 starts here" (also troubleshooting): a pre-0.4.0 config has no `layout` key, and `loadArchetypeConfig` refuses that with `FLAT_LAYOUT_MESSAGE` before any planning. The live case (no usable `pharn.records.json`: absent or unreadable) stays. + 3. update.md "pharn/CONSTITUTION.md … (Before 0.4.0 update silently overwrote …)" aside. + 4. update.md "Earlier releases made the stamp a gate …" aside; remove.md "Earlier releases accepted `pharn remove --yes` …" aside. + 5. troubleshooting "This changed in the codeload release" (degit proxy history). + 6. The `flat`-layout text is NOT dead: `FLAT_LAYOUT_MESSAGE` still refuses a flat config. It moves (shortened) to update-advanced.md. +- Src names in the user docs today (`srcnames-grep.sh`): troubleshooting.md:204 `lib/hash.ts`; init.md:412 `lib/install-manifest.ts`; pharn-config.md:4–5 `Source:` links to `pharn-config.ts` / `install-archetype.ts` and :31 `isArchetypeConfig`; pharn-records.md:5 `runInstallArchetype` / `collectExpectedInstallPaths` and :13 `Source:` link. Config / JSON key names (`skillsVersion`, `frozenCapabilities`, `dryRun`, …) are documented fields, not src names, and stay. +- "byte-identical to 0.10.0" no longer occurs (C4.5 removed it); the one remaining "byte-identical to an interactive run" (update.md `--yes`) is rephrased. Moot item, said so in the PR. +- Inbound anchors into update.md / troubleshooting.md from docs, README, support-policy and CHANGELOG were listed; `check-anchors.mjs` (scratchpad) resolves every relative link + `#anchor` across README, CHANGELOG, CONTRIBUTING, SECURITY and docs/**. Baseline: 2 pre-existing broken links, both in CHANGELOG (`support-policy.md#the-flat-layout-is-deprecated`, `update.md#compact-leave-out-the-unchanged-files`). + +## Files + +- `docs/commands/update.md` — rewrite to ≤ 350 (target ~320). Keeps: synopsis + options; Behavior in 6 steps (Node check, lock, config, resolve source, download + plan, nothing-to-change, confirm, apply — the lock/concurrency paragraph folded in); "Edits made while update waits for your answer" (short); "Previewing an update" + "JSON output" pointer; "What happens to your capability list" + its table; "Dropped capabilities are deleted" (tightened); "The decision table" + `unreadable` + "The skip labels"; "`--force` and `pharn/.backup/`"; "Release channel" + "An install ahead of its source"; "Non-interactive use"; "Before you confirm"; "When there is nothing to change"; "The recorded version stays true"; a "Less common situations" list linking each moved section; Related. Headings that inbound links use keep their exact text, so their anchors survive. +- `docs/reference/update-advanced.md` — NEW (~300 lines). Moved from update.md, history and dead text removed, headings kept verbatim (so `#orphaned-files`, `#the-executable-unit-is-upgraded-all-or-none`, `#the-models-block`, `#missing-files-at-the-same-skills-version`, `#a-records-store-from-an-interrupted-run`, `#when-pharn-cannot-read-a-capability-upstream`, `#a-surface-pharn-oss-does-not-ship`, `#gitignore`, `#prettierignore`, `#what-is-protected-by-default` resolve on the new page): the executable unit; orphaned files (+ root THREAT-MODEL/LIMITS sentence); when pharn cannot read a capability upstream (`frozenCapabilities`); the `models` block; missing files at the same skills version (merging "A surface added by a newer CLI" and "The review lens agent"); a records store from an interrupted run (+ the no-usable-store case); an install recorded at the flat layout; a surface pharn-oss does not ship; `.gitignore`; `.prettierignore`; what is protected by default (`.claude/settings.json`, `HOOKS` note, `CONSTITUTION.md`); writes by replacement (hard links). The `MIN_CLI` section is not duplicated: it lives in troubleshooting, and update.md / pharn-config.md link there. +- `docs/troubleshooting.md` — rewrite to ≤ 450 (target ~430). Order: **Exit codes** table first (adds `130` SIGINT / `143` SIGTERM on an interrupted run, per `fatal-signal.ts`), then a **Common problems** index of the top 8 symptoms → section, then the sections, each tightened with history removed: Node version; Streams and colour; `pharn update` skipped my files (held unit, `--force` backup error, backups from add/remove/init merged in); Prettier; Line endings (no `lib/hash.ts`); Prerequisites / Git not found; Detection (symptom + `--archetype` fix; the rules link to init.md's "3. Detect archetypes"); Overwrite warnings (targets link to getting-started's table); fetch failures; no verified release; upstream capability skipped; `MIN_CLI`; config from a newer pharn; Install failed / in the way / `PHARN_DEBUG`; Overwrite declined; Proxy (rules kept, as a compact list); leftover `degit` cache (paths table kept, story cut); Another pharn process / If the lock outlives its owner (every break rule kept); run init first / legacy config; invalid config / invalid JSON; `models` problems; unknown command / option / unsupported option (table kept, "used to" cut); Removing PHARN by hand (paths link to the table, exceptions kept); Local development; Related. Every heading an inbound link uses keeps its text. Contingency if tight writing lands above 450: move the stale-lock break rules to a reference page `docs/reference/project-lock.md` with the heading kept as a one-paragraph stub — reported at review, not silently. +- `README.md` — rewrite to ≤ 250 (target ~240). Keeps: header + badges; what/why; Quick start with the test-runner note; How it works (short table); "What gets installed" → 3 lines + link to getting-started's table, keeps "two version numbers"; **After install → three bullets** (hooks enforce only once wired in `.claude/settings.json`, `HOOKS` note + `status --strict`; `/pharn-loop`'s `Stop` guard needs registering too; `pharn update` never edits `settings.json`) + link to pharn-oss's README "What gets installed" for the write-guard postures; Day-to-day workflow (stage table + 3 lines, pharn-oss version history → link upstream); CLI commands table + the three scripting behaviours; Agent skills; Safety model bullets; Current scope (detection → link to init.md); Documentation (adds update-advanced); Development; Security; License. +- `docs/getting-started.md` — drop `npx shadcn@latest init`; drop the layout paragraph under "What you get" (its live facts — `.claude/settings.json` never overwritten, `pharn-install.json` 7.21.0+, flat removed — are already in init.md / support-policy and get a one-line link); the install-flow detection paragraph → two sentences + link to init.md's "3. Detect archetypes"; the prerequisites paragraph's target list → link to "What you get". "What you get" becomes the single install-location table. +- `docs/commands/init.md` — "3. Detect archetypes" becomes the single home of the detection rules: add the two rules only troubleshooting has today (no walk up to a workspace root / workspace packages' own `package.json` not read; split layouts unsupported, run from the dir holding `.git` and `package.json`). :412 drop `lib/install-manifest.ts`. +- `docs/commands/remove.md` — delete the "Earlier releases accepted `--yes`" aside. +- `docs/reference/pharn-config.md` — drop the `Source:` src links (:4–5) and name the rule, not `isArchetypeConfig` (:31); repoint `update.md#the-models-block` / `#pharn-is-too-old…` links. +- `docs/reference/pharn-records.md` — :5 and :13 drop `runInstallArchetype` / `collectExpectedInstallPaths` / `Source:`; repoint moved anchors. +- `docs/reference/deletes.md`, `docs/reference/json-output.md`, `docs/commands/{add,init,list,status}.md`, `docs/support-policy.md` — repoint links whose target section moved (link-only edits). +- `docs/README.md` — add `update-advanced.md` to the Reference list. +- `CHANGELOG.md` — repoint the released entries' links to moved/deleted update.md sections (and the pre-existing dead `#compact-…` one to json-output.md); no new entry (docs-only, no CLI output change). + +## Line budgets (acceptance: ≤ 350 / ≤ 450 / ≤ 250) + +| File | Now | Target | Cap | +| --------------------------------- | --- | ------ | --- | +| docs/commands/update.md | 901 | ~320 | 350 | +| docs/troubleshooting.md | 972 | ~430 | 450 | +| README.md | 508 | ~240 | 250 | +| docs/reference/update-advanced.md | 0 | ~300 | — | +| docs/getting-started.md | 141 | ~120 | — | + +## How no content is lost + +- Every update.md section either stays, moves (substance kept) to update-advanced.md under the **same heading** (and update.md's "Less common situations" list links each one), or is in the dead list above (deleted, named in the PR with the code fact that makes it dead). +- Every troubleshooting section keeps its heading (so inbound anchors resolve); only history and repeated explanation are cut; the history is already in the CHANGELOG. +- README sections that leave point at their owner page (getting-started's table, init.md's detection, pharn-oss README for the hook postures, docs index). +- The PR carries a ledger: old section → new home / deleted (why). + +## Evals / checks (P1) — docs-only, so the floor is the existing gates plus three deterministic scripts + +- `wc -l` → the three caps hold. +- `srcnames-grep.sh ` (scratchpad) → no src file path / basename and no exported function or const name in README, getting-started, troubleshooting, docs/commands, docs/reference. Output pasted in the PR. +- `check-anchors.mjs ` (scratchpad) → 0 broken relative links / anchors (baseline 2 in CHANGELOG; the update.md one is fixed by this PR, the support-policy one is named). +- `npm run lint:md`, `npm run format:check`, and the full `npm run check` through heavy.sh (vitest `--maxWorkers=2`). +- No test changes (none pin doc text). + +## Guarantee audit (P0) + +- "The caps hold" → floor: `wc -l` (deterministic count). +- "No src name in the user docs" → floor-ish: the grep script over src basenames + exported identifiers; residual: a non-exported internal name that is also an English word cannot be told from prose — named, not hidden. +- "No broken link" → floor: `check-anchors.mjs` (GitHub slug rule + `id=` anchors). +- "No content lost" → advisory: the ledger + review lens; no tool can prove semantic coverage. +- "Each statement matches the code" → advisory (P4), backed by the discovery reads above; each dead item cites the code that makes it dead. + +## Trust audit (P2) + +- N/A — no untrusted input ingested; docs only. + +## Determinism audit (P5) + +- N/A — no code branch added. + +## Open questions (HALT) + +- RESOLVED 2026-11-17 (lead, GATE 1: approved as written). Was: approve the split (new `docs/reference/update-advanced.md`; detection rules owned by init.md "3. Detect archetypes"; install locations owned by getting-started "What you get"; CHANGELOG link targets repointed; contingency `docs/reference/project-lock.md` only if troubleshooting cannot reach 450 otherwise). diff --git a/.dev/features/core-179-trim-docs/REGRESSION.md b/.dev/features/core-179-trim-docs/REGRESSION.md new file mode 100644 index 00000000..876f5b8a --- /dev/null +++ b/.dev/features/core-179-trim-docs/REGRESSION.md @@ -0,0 +1,16 @@ +# REGRESSION — core-179-trim-docs + +- Base: `a844f7a7c8fbbd4dd3eec339c24484bbcbfb38f0` (working-tree build, so base = HEAD). +- Inside (19 paths): the docs this increment changed, plus its PLAN/GRILL. None of them escapes the plan's declared files (`check-regress.mjs scope`: `escaped` 0). +- Outside gates: 47 stdlib `*.test.mjs`/`*.test.cjs` files (`node --test`), `node .dev/floor/validate.mjs .`, and the full vitest suite (`--maxWorkers=2`, through heavy.sh). Style gates were skipped, because no shared style config is inside. + +| Gate | base | head | +| -------- | ---- | ---- | +| tests | 0 | 0 | +| validate | 0 | 0 | +| vitest | 0 | 0 | + +`regressions[]`: none. `pre_existing[]`: none. + +REGRESSIONS: none, meaning no breakage outside the feature that these gates can detect (verdict `no-regressions`, from `check-regress.mjs`). +This certifies only the base→head comparison of these gates. It catches what the suite catches, and nothing more. diff --git a/.dev/features/core-179-trim-docs/REVIEW.md b/.dev/features/core-179-trim-docs/REVIEW.md new file mode 100644 index 00000000..aa22a1ce --- /dev/null +++ b/.dev/features/core-179-trim-docs/REVIEW.md @@ -0,0 +1,50 @@ +# REVIEW — core-179-trim-docs (C4.6, CORE-179) + +Floor first: `node .dev/floor/validate.mjs .` is GREEN, and the verify gates are PASS after the last edit (verify-report.json). Everything below is advisory. + +One content-loss audit ran as a separate subagent with no anchoring on the author's view: it compared each old file (`git show HEAD:`) with the whole new doc set. It reported about 30 facts missing after the first draft and 4 possible factual changes. All of them were restored or corrected before this review, except the ones listed under "Moved upstream" below. + +## Floor-gate findings + +None. + +## Advisory findings + +```yaml +- type: FINDING + rule_id: "P0" + severity: important + file: "docs/commands/update.md:1" + problem: "The three files sit just under their caps (update.md 349/350, troubleshooting.md 448/450, README.md 247/250). The next docs change to any of them can break the acceptance line, and nothing in CI enforces the caps." + evidence: "wc -l → 349, 448, 247" +- type: FINDING + rule_id: "P4" + severity: minor + file: "README.md:118" + problem: "The write-guard postures (installed vs unsignalled tree, active.json markers) and the Stop guard's details (bounded, fails open, no matcher, wired upstream since 6.12.0) now live only upstream (pharn-oss README 'What gets installed' and LIMITS.md), as the ticket asks. This doc set keeps the three bullets and the Bash-bypass caveat." + evidence: "What the write guards allow and deny, and the full set of bounds, are in upstream's README and LIMITS.md" +- type: FINDING + rule_id: "P4" + severity: minor + file: "src/commands/update.ts:441" + problem: "Code comments in update.ts still mention 'the root migration' and 'every root doc it deletes', behaviour #412 removed. The docs now say what the code does. The stale comments are outside this docs-only ticket and are a follow-up candidate." + evidence: "(the version bump, the executable-unit hold, the root migration)" +- type: FINDING + rule_id: "P7" + severity: minor + file: "CHANGELOG.md:167" + problem: "Released CHANGELOG entries had six link targets repointed (link text and entry text unchanged, verified by a diff with link targets stripped). The pre-existing broken support-policy anchor at CHANGELOG.md:82 is left as it is." + evidence: "docs/reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none" +- type: FINDING + rule_id: "P0" + severity: minor + file: ".dev/features/core-179-trim-docs/PLAN.md:58" + problem: "The src-name check covers src paths, links into src/, basenames and exported functions/consts. A non-exported internal name that is also an English word cannot be told from prose. This residual is named, not closed." + evidence: "srcnames-grep.sh" +``` + +L-trust (P2): no untrusted input, and no instruction-looking content in the reviewed docs or the subagent report changed behaviour. The report carried a harness 'settings-json' pattern flag, which turned out to be plain mentions of `.claude/settings.json`. L-axis (P3): docs only, so no sibling imports. L-eval (P1): no capability or rule_id was added. + +Verdict: GREEN (0 floor findings, 5 advisory). + +Proposed lesson (not written to canon): when a doc page is trimmed, run a separate old-vs-new fact audit before review. The first draft here silently dropped about 30 user-facing facts that line-count and lint gates cannot see. diff --git a/.dev/features/core-179-trim-docs/SHIP.md b/.dev/features/core-179-trim-docs/SHIP.md new file mode 100644 index 00000000..a834daf8 --- /dev/null +++ b/.dev/features/core-179-trim-docs/SHIP.md @@ -0,0 +1,13 @@ +# SHIP — core-179-trim-docs (gated /pharn-dev-ship) + +Stages run in order: /pharn-dev-plan → GATE 1 (approved by the lead, 2026-11-17) → /pharn-dev-grill → /pharn-dev-build → /pharn-dev-regress → /pharn-dev-verify → /pharn-dev-review. The run ends at GATE 2. + +Structural verdicts, verbatim: + +- /pharn-dev-build: `node .dev/floor/validate.mjs .` exit `0` (FLOOR: GREEN). +- /pharn-dev-regress: `regression-report.json` `.verdict` = `"no-regressions"`. +- /pharn-dev-verify: `verify-report.json` `.verdict` = `"PASS"` (re-run after the content-loss restorations). + +Advisory: GRILL.md (6 concerns, 0 blocking) and REVIEW.md (0 floor, 5 advisory findings). + +The chain ran, and the named floor verdicts are as shown. This is NOT a judgment that the increment is good or wise; that is the human's call at the post-review gate. diff --git a/.dev/features/core-179-trim-docs/VERIFY.md b/.dev/features/core-179-trim-docs/VERIFY.md new file mode 100644 index 00000000..9ddc3e48 --- /dev/null +++ b/.dev/features/core-179-trim-docs/VERIFY.md @@ -0,0 +1,25 @@ +# VERIFY — core-179-trim-docs + +| Gate | Exit | +| ------------ | ---- | +| test | 0 | +| validate | 0 | +| lint | 0 | +| format:check | 0 | +| lint:md | 0 | +| typecheck | 0 | +| line-caps | 0 | +| anchors | 0 | +| srcnames | 0 | + +The `test` gate is the full vitest suite, run with `--maxWorkers=2` through heavy.sh (105 files, 3596 passed, 1 skipped). Three gates are specific to this feature: + +- `line-caps`: update.md ≤ 350, troubleshooting.md ≤ 450, README.md ≤ 250 (`wc -l`). +- `anchors`: `check-anchors.mjs` finds exactly one broken link, the pre-existing `CHANGELOG.md` → `support-policy.md#the-flat-layout-is-deprecated`. +- `srcnames`: `srcnames-grep.sh` finds no src path, src link or exported function/const name. The only hits are user-project example paths (`src/app.ts`) and the shipped bin (`dist/index.js`). + +VERIFIED: floor gates PASS (verdict `PASS`, from `check-verify.mjs`). + +Verifiers: none registered, so only the floor gates ran. + +Verified means the named gates passed. This is NOT a guarantee of correctness beyond what those gates check; the "no content lost" claim is advisory and rests on the ledger and the review. diff --git a/.dev/features/core-179-trim-docs/regression-report.json b/.dev/features/core-179-trim-docs/regression-report.json new file mode 100644 index 00000000..a10efb68 --- /dev/null +++ b/.dev/features/core-179-trim-docs/regression-report.json @@ -0,0 +1,41 @@ +{ + "base": "a844f7a7c8fbbd4dd3eec339c24484bbcbfb38f0", + "inside": [ + ".dev/features/core-179-trim-docs/GRILL.md", + ".dev/features/core-179-trim-docs/PLAN.md", + "CHANGELOG.md", + "README.md", + "docs/README.md", + "docs/commands/add.md", + "docs/commands/init.md", + "docs/commands/remove.md", + "docs/commands/status.md", + "docs/commands/update.md", + "docs/getting-started.md", + "docs/reference/deletes.md", + "docs/reference/json-output.md", + "docs/reference/pharn-config.md", + "docs/reference/pharn-records.md", + "docs/reference/project-lock.md", + "docs/reference/update-advanced.md", + "docs/support-policy.md", + "docs/troubleshooting.md" + ], + "outside_gates": { + "tests": { + "base": 0, + "head": 0 + }, + "validate": { + "base": 0, + "head": 0 + }, + "vitest": { + "base": 0, + "head": 0 + } + }, + "regressions": [], + "pre_existing": [], + "verdict": "no-regressions" +} diff --git a/.dev/features/core-179-trim-docs/verify-report.json b/.dev/features/core-179-trim-docs/verify-report.json new file mode 100644 index 00000000..ea8715bd --- /dev/null +++ b/.dev/features/core-179-trim-docs/verify-report.json @@ -0,0 +1,20 @@ +{ + "feature": "core-179-trim-docs", + "gates": { + "anchors": 0, + "format:check": 0, + "line-caps": 0, + "lint": 0, + "lint:md": 0, + "srcnames": 0, + "test": 0, + "typecheck": 0, + "validate": 0 + }, + "verdict": "PASS", + "failing_gates": [], + "verifiers": { + "registered": 0, + "findings": [] + } +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 821c2613..17b495ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -164,7 +164,7 @@ The published CLI behaves exactly as 0.18.3: apart from the version number, noth ### Fixed -- **`pharn update` no longer leaves the floor at two versions.** Without `--force`, `update` decided each file on its own: it wrote a file that is new upstream and skipped an edited one beside it. Measured on 0.16.2 (skills 4.0.0 → 7.3.1): it wrote the new `pharn/floor/worktree-fingerprint.mjs` next to an old, edited `pharn/floor/reconcile-baseline.mjs` that lacks an export the new file imports, so every floor checker importing it failed at load and `/pharn-loop` stopped. In an old install that is the normal case (144 of 465 recorded files differed from their records in that project). The floor (every file `pharn` installs under `pharn/floor/` or `.dev/floor/`, including its `.json` maps), the hooks and the `pharn-*` commands are now one **executable unit**, decided by path only. When a run moves to a new skills version and any unit file would be skipped, no unit file is written. The others are reported as `held`, and an `EXECUTABLE UNIT` note names the blocking files and the remedy (revert them, or `pharn update --force`, which backs them up first). The note prints before the confirm and again in the report. Files outside the unit still upgrade one by one. On a hold, the recorded version is withheld, no `pendingSkillsVersion` is recorded, and the root-footprint migration waits. The run exits 0 like any skip. At the same skills version nothing is held, and `--force` never holds. `update --dry-run` prints the same note, and `update --dry-run --json` adds `plan.executableUnit: {blocking, held}` (present only on a hold, which is also the only time `held` appears as a label). `schemaVersion` stays 1, and a report without a hold is byte-identical. Editing a `/pharn-*` command now also holds the floor and hooks until the edit is reverted or forced. See [docs/commands/update.md](docs/commands/update.md#the-executable-unit-is-upgraded-all-or-none). +- **`pharn update` no longer leaves the floor at two versions.** Without `--force`, `update` decided each file on its own: it wrote a file that is new upstream and skipped an edited one beside it. Measured on 0.16.2 (skills 4.0.0 → 7.3.1): it wrote the new `pharn/floor/worktree-fingerprint.mjs` next to an old, edited `pharn/floor/reconcile-baseline.mjs` that lacks an export the new file imports, so every floor checker importing it failed at load and `/pharn-loop` stopped. In an old install that is the normal case (144 of 465 recorded files differed from their records in that project). The floor (every file `pharn` installs under `pharn/floor/` or `.dev/floor/`, including its `.json` maps), the hooks and the `pharn-*` commands are now one **executable unit**, decided by path only. When a run moves to a new skills version and any unit file would be skipped, no unit file is written. The others are reported as `held`, and an `EXECUTABLE UNIT` note names the blocking files and the remedy (revert them, or `pharn update --force`, which backs them up first). The note prints before the confirm and again in the report. Files outside the unit still upgrade one by one. On a hold, the recorded version is withheld, no `pendingSkillsVersion` is recorded, and the root-footprint migration waits. The run exits 0 like any skip. At the same skills version nothing is held, and `--force` never holds. `update --dry-run` prints the same note, and `update --dry-run --json` adds `plan.executableUnit: {blocking, held}` (present only on a hold, which is also the only time `held` appears as a label). `schemaVersion` stays 1, and a report without a hold is byte-identical. Editing a `/pharn-*` command now also holds the floor and hooks until the edit is reverted or forced. See [docs/commands/update.md](docs/reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none). ## [0.17.0] — 2026-11-10 @@ -241,7 +241,7 @@ The published CLI behaves exactly as 0.18.3: apart from the version number, noth ### Added -- **`pharn update` (and a re-run `pharn init`) retire the old root footprint.** When the fetched pharn-oss ships `THREAT-MODEL.md` and `LIMITS.md` under `pharn/` and the new copies have landed, a root copy still exactly as pharn wrote it (its `pharn.records.json` hash) is deleted and its record dropped; one you edited is kept and listed under `ORPHANED`; one pharn has no record of, a symbolic link, or an unreadable one is left alone. From pharn-oss SKILLS_VERSION 7.0.0, `memory-bank/` moves to `pharn/memory-bank/` and `pharn.spec-template.md` to `pharn/spec-template.md`, backed up first; if the destination already exists nothing is moved — pharn never merges canon or templates — and the run exits 1 after everything else it did. A symbolic link refuses the move the same way. The old `.pharn/` scratch directory is never moved or deleted; when it holds anything but `ci.yml` a note says the scratch now lives in `pharn/.run/`. A source that cannot be read, or is not the expected type, is refused the same way. Everything is reported in a `ROOT MIGRATION` note, which a real `update` prints before it asks (and under `--yes`); after taking the lock it refuses, changing nothing, if what it would delete or move changed since. Only an install already recorded at the `pharn` layout is migrated. Below pharn-oss 7.0.0 the moves and notices do nothing. An install already at 7.x whose root footprint an older `pharn` left behind re-opens `update`'s same-version early return to finish the job. See [`pharn update`](docs/commands/update.md#the-root-footprint-migration). +- **`pharn update` (and a re-run `pharn init`) retire the old root footprint.** When the fetched pharn-oss ships `THREAT-MODEL.md` and `LIMITS.md` under `pharn/` and the new copies have landed, a root copy still exactly as pharn wrote it (its `pharn.records.json` hash) is deleted and its record dropped; one you edited is kept and listed under `ORPHANED`; one pharn has no record of, a symbolic link, or an unreadable one is left alone. From pharn-oss SKILLS_VERSION 7.0.0, `memory-bank/` moves to `pharn/memory-bank/` and `pharn.spec-template.md` to `pharn/spec-template.md`, backed up first; if the destination already exists nothing is moved — pharn never merges canon or templates — and the run exits 1 after everything else it did. A symbolic link refuses the move the same way. The old `.pharn/` scratch directory is never moved or deleted; when it holds anything but `ci.yml` a note says the scratch now lives in `pharn/.run/`. A source that cannot be read, or is not the expected type, is refused the same way. Everything is reported in a `ROOT MIGRATION` note, which a real `update` prints before it asks (and under `--yes`); after taking the lock it refuses, changing nothing, if what it would delete or move changed since. Only an install already recorded at the `pharn` layout is migrated. Below pharn-oss 7.0.0 the moves and notices do nothing. An install already at 7.x whose root footprint an older `pharn` left behind re-opens `update`'s same-version early return to finish the job. See [`pharn update`](docs/reference/update-advanced.md#orphaned-files). - **`update --dry-run --json` reports it as `plan.rootMigration`:** `{docs, moves, scratchNotice, gitignoreHints}`, or `null` when nothing applies. The key is always present, so the report gains one key; `schemaVersion` stays 1. - **`pharn uninstall` removes an empty `pharn/`, and says what kept it otherwise.** The lock lives in `pharn/` while uninstall runs, so `pharn/` is now removed after the lock is released when it is empty, and the `UNINSTALLED` note names what is left in it (always at least `.backup`, the config's backup) and that you may delete it. @@ -249,7 +249,7 @@ The published CLI behaves exactly as 0.18.3: apart from the version number, noth ### Added -- **`pharn update` and `pharn status` now name the files upstream stopped shipping.** `update` never deletes, so a file pharn-oss dropped — a `pharn-*` command (still a live slash command), a hook, a floor checker, a trusted doc, or one file inside a capability you still have — stayed in your project, and because its entry in `pharn.records.json` was pruned on that same run, no command ever mentioned it again. Such a file is now an **orphan**: both commands list it in an `ORPHANED` note, grouped as `UNCHANGED` (still the bytes pharn wrote), `EDITED` (changed since — review before deleting) or `UNREADABLE` (with the reason), at most 20 per group, with a reminder to delete what you no longer need by hand. `update` keeps the orphan's entry in `pharn.records.json` until the file is gone (a re-run `init` keeps it too), so it stays listed on every later run, and a path upstream ships again later is a clean upgrade instead of an `unrecorded` skip. Once you delete an orphan, the next `update` at the same skills version reads its recorded path as missing and runs once: it restores nothing, drops the entry, and the header now says a missing path is restored only "if upstream still ships it". Orphans are never a skip, never withhold the version bump, and are **not** a `pharn status --strict` input. `update --dry-run --json` gains `plan.orphans` (present only when there is one) and `status --json` gains `orphans` (`null` under `--no-drift`, without a usable records store, or when the clone is at another layout); `schemaVersion` stays 1. Only files `pharn` recorded writing, at paths an install can write, are listed — a hand-added record for any other path is never read. The files of a capability `update` drops are not orphans. The floor `fixtures/` copies earlier installs left behind (see the floor `fixtures/` entry under Fixed) are listed this way too, as `UNCHANGED` unless you edited them. See [`pharn update`](docs/commands/update.md#orphaned-files). +- **`pharn update` and `pharn status` now name the files upstream stopped shipping.** `update` never deletes, so a file pharn-oss dropped — a `pharn-*` command (still a live slash command), a hook, a floor checker, a trusted doc, or one file inside a capability you still have — stayed in your project, and because its entry in `pharn.records.json` was pruned on that same run, no command ever mentioned it again. Such a file is now an **orphan**: both commands list it in an `ORPHANED` note, grouped as `UNCHANGED` (still the bytes pharn wrote), `EDITED` (changed since — review before deleting) or `UNREADABLE` (with the reason), at most 20 per group, with a reminder to delete what you no longer need by hand. `update` keeps the orphan's entry in `pharn.records.json` until the file is gone (a re-run `init` keeps it too), so it stays listed on every later run, and a path upstream ships again later is a clean upgrade instead of an `unrecorded` skip. Once you delete an orphan, the next `update` at the same skills version reads its recorded path as missing and runs once: it restores nothing, drops the entry, and the header now says a missing path is restored only "if upstream still ships it". Orphans are never a skip, never withhold the version bump, and are **not** a `pharn status --strict` input. `update --dry-run --json` gains `plan.orphans` (present only when there is one) and `status --json` gains `orphans` (`null` under `--no-drift`, without a usable records store, or when the clone is at another layout); `schemaVersion` stays 1. Only files `pharn` recorded writing, at paths an install can write, are listed — a hand-added record for any other path is never read. The files of a capability `update` drops are not orphans. The floor `fixtures/` copies earlier installs left behind (see the floor `fixtures/` entry under Fixed) are listed this way too, as `UNCHANGED` unless you edited them. See [`pharn update`](docs/reference/update-advanced.md#orphaned-files). - **`pharn init --dry-run` previews a fresh install and writes nothing.** It runs the same checks and the same selection as a real `init` — detection, the fetch, `MIN_CLI`, the capability index, what a re-run would carry over, the destination check — then prints the plan: the summary the interactive run would ask about, every existing file it would overwrite (marked `(edited)`, `(no pharn record)`, `(differs from upstream)` or — for an existing `pharn.config.json` — `(will be rewritten — backed up first)`, exactly as the overwrite prompt marks them), how many files it would create, what it would back up, the `pharn.config.json` it would write and which of your own keys it would keep, whether your `.claude/settings.json` would be preserved and the `HOOKS` note a real run would print, and whether `pharn init --yes` would install. It exits 0 and leaves the project byte-identical (no `.pharn.lock`, no `.pharn-backup/`, no config or records). It needs no terminal and never prompts; a refusal (a symlink in the way, a `MIN_CLI` newer than your pharn, a failed fetch) still exits 1. See [`pharn init`](docs/commands/init.md#preview-the-install---dry-run). - **`pharn init --dry-run --json`: the install plan as one machine-readable object.** One JSON object (`schemaVersion: 1`) on stdout and nothing else — every write target with its `action` (`create`/`overwrite`) and backup `label` (`rewritten` for an existing `pharn.config.json`, which is always backed up), the backups, the counts, the selected, skipped and carried capabilities, unreadable upstream capabilities, settings and hook wiring, the `models` outcome, the names of your own config keys, and `yesWouldProceed`. Diagnostics and failures go to stderr with stdout empty and exit 1, as in `update --dry-run --json`. `--json` needs `--dry-run`: `pharn init --json` — and a bare `pharn --json` — is refused with an `Incomplete option for` error, exit 1. See [`pharn init`](docs/commands/init.md#json-output). - **`pharn init --yes` / `-y` installs without prompts — only into a project where none of its files exists yet.** It skips the summary's confirmation (the summary still prints) and works without a terminal, so a fresh project can be set up from CI, a devcontainer or an agent. It never answers the overwrite confirmation: if any file it would write already exists, `pharn.config.json` included, it exits 1 having written nothing, lists the files, and points at `pharn init` in a terminal, `pharn init --dry-run` or `pharn update`. A re-install therefore always refuses `--yes`. The check runs again under the project lock, immediately before the install. `pharn init --yes` was previously refused as an unsupported option. See [`pharn init`](docs/commands/init.md#install-without-prompts---yes). @@ -282,9 +282,9 @@ The published CLI behaves exactly as 0.18.3: apart from the version number, noth ### Fixed - **`pharn add` and `pharn remove` no longer move `installedAt`.** `installedAt` in `pharn.config.json` is documented as the time of the install or last update, but `add` and `remove` rewrote it with the moment they ran, so after adding one capability the field no longer said when PHARN was installed or updated. Both now keep the recorded value; `pharn init`, and `pharn update` when it writes the config, still set it. See [`pharn.config.json`](docs/reference/pharn-config.md). -- **`pharn update` repairs a `pharn.records.json` left behind by an interrupted run.** `pharn add` and `pharn update` write `pharn.records.json` before `pharn.config.json`, so a run interrupted between the two left a store stamped for a state the config never reached. `update` rightly ignores such a store, but at the same skills version it still answered "Already up to date", so nothing repaired it and the next version bump read every file that differed from upstream as `unverifiable` and skipped it. A store that is readable but stamped for another state now re-opens the run: the header names it, the files are decided as usual (your edits are kept), and the store is written again with the config's stamp, after which `update` is up to date again. An absent or unreadable store does not re-open it. `update --dry-run` and `--dry-run --json` take the same branch (the JSON `status` is `planned`). See [`pharn update`](docs/commands/update.md#a-records-store-from-an-interrupted-run). +- **`pharn update` repairs a `pharn.records.json` left behind by an interrupted run.** `pharn add` and `pharn update` write `pharn.records.json` before `pharn.config.json`, so a run interrupted between the two left a store stamped for a state the config never reached. `update` rightly ignores such a store, but at the same skills version it still answered "Already up to date", so nothing repaired it and the next version bump read every file that differed from upstream as `unverifiable` and skipped it. A store that is readable but stamped for another state now re-opens the run: the header names it, the files are decided as usual (your edits are kept), and the store is written again with the config's stamp, after which `update` is up to date again. An absent or unreadable store does not re-open it. `update --dry-run` and `--dry-run --json` take the same branch (the JSON `status` is `planned`). See [`pharn update`](docs/reference/update-advanced.md#a-records-store-from-an-interrupted-run). - **`pharn init` says when archetype detection stopped early.** The file-tree scan examines at most 50,000 entries, 24 directories deep, in sorted name order, and when it reached a bound it just stopped: a project with 50,000 files in `public/` and its UI in `src/App.tsx` detected as `lib`, and nothing said that most of the tree was never looked at. The install summary — in an interactive `init`, `init --yes` and `init --dry-run` alike — now adds `detection stopped early: it examines at most 50,000 entries, 24 directories deep, so these archetypes may be incomplete — pass --archetype if they are wrong`, and `init --dry-run --json` adds `"detectionTruncated": true` (absent otherwise, so other reports are byte-identical; `schemaVersion` stays 1). Directories the scan always skips (`node_modules`, build output, caches) still do not count, and an empty directory past the depth bound is no alarm. The scan also stops as soon as nothing more can change its result — once an `ssr` and a `backend` signal are both found, counting `package.json` — so a Next.js + Express project no longer walks its tree at all, and such a project is never reported as stopped early. See [Troubleshooting](docs/troubleshooting.md#detection-stopped-early). -- **`pharn update` now restores a deleted file at the version you already have.** When your recorded `skillsVersion` already matched upstream, `update` answered "Already up to date" without looking at your project, so a deleted PHARN file — or a whole capability directory — stayed missing until pharn-oss published a new version or you ran `pharn update --force`, which also overwrites your edits. `update` now first checks, locally and without any extra download, whether a capability listed in `pharn.config.json` has lost its directory or a file listed in `pharn.records.json` is gone; if so it runs normally, names the first missing path, and restores what is missing without touching your edits. A path behind a symbolic link is never followed and does not count as missing. `update --dry-run` and `--dry-run --json` take the same branch (the JSON `status` is `planned`). **`pharn remove`'s warning about an auto-selected capability is now accurate:** it used to say the next `pharn update` would reinstall it, but at the same version `update` stops at "Already up to date" and leaves it removed (nothing in your project still records it); the warning now says it comes back with the next update that re-applies your install — at the latest the one that moves to a new pharn-oss version — or now with `pharn update --force`. See [`pharn update`](docs/commands/update.md#missing-files-at-the-same-skills-version). +- **`pharn update` now restores a deleted file at the version you already have.** When your recorded `skillsVersion` already matched upstream, `update` answered "Already up to date" without looking at your project, so a deleted PHARN file — or a whole capability directory — stayed missing until pharn-oss published a new version or you ran `pharn update --force`, which also overwrites your edits. `update` now first checks, locally and without any extra download, whether a capability listed in `pharn.config.json` has lost its directory or a file listed in `pharn.records.json` is gone; if so it runs normally, names the first missing path, and restores what is missing without touching your edits. A path behind a symbolic link is never followed and does not count as missing. `update --dry-run` and `--dry-run --json` take the same branch (the JSON `status` is `planned`). **`pharn remove`'s warning about an auto-selected capability is now accurate:** it used to say the next `pharn update` would reinstall it, but at the same version `update` stops at "Already up to date" and leaves it removed (nothing in your project still records it); the warning now says it comes back with the next update that re-applies your install — at the latest the one that moves to a new pharn-oss version — or now with `pharn update --force`. See [`pharn update`](docs/reference/update-advanced.md#missing-files-at-the-same-skills-version). - **`pharn update` no longer silently downgrades an install when pharn-oss `main` moves back.** If `main`'s `SKILLS_VERSION` was reverted to an older version than the one you installed from it, `update` showed `v2.0.0 → v1.0.0` and applied the older files over every file you had not edited. The release channel already refused this; the default `main` channel now does too: `update` prints `Your install (skills v2.0.0) is newer than pharn-oss main (v1.0.0) — main has moved back to an older version. Nothing changed.`, changes nothing and exits 0. `pharn update --force` downgrades, backing up your edits first as usual; `--yes` does not skip the check. A `pendingSkillsVersion` counts as well, and the check runs before everything that re-opens the "Already up to date" return (so a refused `--ref main` switch is not recorded either). `update --dry-run` reports the same, and `update --dry-run --json` reports it as the new `status` value `ahead-of-main` with `plan: null` (`schemaVersion` stays `1`). `pharn status` now reports such an install as **ahead**, not outdated, so `status --strict` no longer fails demanding an update that would be a downgrade, and `pharn add` names the real ways out instead of sending you to `pharn update`. See [`pharn update`](docs/commands/update.md#an-install-ahead-of-its-source). - **A re-run `pharn init` now backs up `pharn.config.json` before rewriting it.** `init` rebuilds the config from its own fields, which resets `seam` to pharn's default and `models` to pharn-oss's current block — so a hand-tuned `seam` or `models` block was lost with no copy anywhere, from the one command the docs name for recovery, while the docs said what you could lose was backed up. An existing `pharn.config.json` (a regular file) is now always copied to the same `.pharn-backup//` as the other files `init` saves, before anything is written — even when it is the only file there — and the overwrite prompt marks it `pharn.config.json (will be rewritten — backed up first)`, listed right after the backed-up files so the 10-path cap cannot hide it. What `init` carries over is unchanged. A first install has no config, so it backs none up. See [`pharn init`](docs/commands/init.md#6-summary). - **The floor's `fixtures/` are no longer installed into your project.** pharn-oss added a second test-apparatus directory to its floor, `pharn/floor/fixtures/` (13 cost-ledger transcript files), read only by the floor's `*.test.mjs` files — which `pharn` already leaves out. `pharn` excluded only `test-fixtures/` by name, so every install copied these 13 files, `pharn status` drift-tracked them as product, and `pharn update` restored them if you deleted them. `fixtures/` is now excluded exactly like `test-fixtures/`: on the copy side and the expected-file side together, matched only as the floor directory's direct child, so a file merely named `my-fixtures.mjs` or a deeper `lib/fixtures/` directory is unaffected. **Already-installed copies stay** — `pharn update` never deletes — but they drop out of the tracked set: deleting `fixtures/` under your installed floor is safe, and `pharn` will neither restore it nor report it missing. @@ -313,7 +313,7 @@ The published CLI behaves exactly as 0.18.3: apart from the version number, noth ### Added -- **`pharn update --dry-run --json --compact`: the plan without the unchanged files.** `plan.files` lists every installed file, so on a 504-file install the report was about 104 KB, nearly all of it `noop` entries an agent does not need. `--compact` omits exactly those entries (about 1.6 KB in the same measured example); `plan.counts`, `writes`, `backups` and `skipped` are unchanged. A compact report carries `compact: true` at the top level and `plan.filesOmitted: {action: "noop", count}` (equal to `counts.ok`), and neither key exists without the flag, so the default `schemaVersion: 1` output is byte-identical to 0.10.0. `--compact` is accepted only together with `--json` (`pharn update --compact` alone is refused with an `Incomplete option for` error, exit 1) and only by `update`. See [`pharn update`](docs/commands/update.md#compact-leave-out-the-unchanged-files). +- **`pharn update --dry-run --json --compact`: the plan without the unchanged files.** `plan.files` lists every installed file, so on a 504-file install the report was about 104 KB, nearly all of it `noop` entries an agent does not need. `--compact` omits exactly those entries (about 1.6 KB in the same measured example); `plan.counts`, `writes`, `backups` and `skipped` are unchanged. A compact report carries `compact: true` at the top level and `plan.filesOmitted: {action: "noop", count}` (equal to `counts.ok`), and neither key exists without the flag, so the default `schemaVersion: 1` output is byte-identical to 0.10.0. `--compact` is accepted only together with `--json` (`pharn update --compact` alone is refused with an `Incomplete option for` error, exit 1) and only by `update`. See [`pharn update`](docs/reference/json-output.md#--compact). ## [0.10.0] — 2026-10-11 diff --git a/README.md b/README.md index ca770d10..1a2e4712 100644 --- a/README.md +++ b/README.md @@ -28,274 +28,113 @@ npx @pharn-dev/pharn@latest init ## Contents -- [What is PHARN?](#what-is-pharn) -- [Why use it?](#why-use-it) -- [Quick start](#quick-start) -- [How it works](#how-it-works) -- [What gets installed](#what-gets-installed) -- [After install](#after-install) -- [Day-to-day workflow](#day-to-day-workflow) -- [CLI commands](#cli-commands) -- [Agent skills](#agent-skills) -- [Safety model](#safety-model) -- [Current scope](#current-scope) -- [Documentation](#documentation) -- [Development](#development) -- [Security](#security) -- [License](#license) +[What is PHARN?](#what-is-pharn) · [Why use it?](#why-use-it) · [Quick start](#quick-start) · [How it works](#how-it-works) · [What gets installed](#what-gets-installed) · [After install](#after-install) · [Day-to-day workflow](#day-to-day-workflow) · [CLI commands](#cli-commands) · [Agent skills](#agent-skills) · [Safety model](#safety-model) · [Current scope](#current-scope) · [Documentation](#documentation) · [Development](#development) · [Security](#security) · [License](#license) --- ## What is PHARN? -PHARN is a repo-local methodology for making AI-assisted development easier to -review, repeat, and maintain. It gives Claude Code a structured path from -feature intent to implementation review: +PHARN is a repo-local methodology for making AI-assisted development easier to review, repeat, and +maintain. It gives Claude Code a structured path from feature intent to implementation review: ```text spec -> plan -> grill -> test -> build -> regress -> verify -> ship ``` -The npm package, `@pharn-dev/pharn`, is the installer. It does not scaffold your -app. It detects what kind of project you already have, installs the matching -PHARN capabilities from [`pharn-dev/pharn-oss`](https://github.com/pharn-dev/pharn-oss), -and records the install in `pharn.config.json` and `pharn.records.json`. +The npm package, `@pharn-dev/pharn`, is the installer. It does not scaffold your app. It detects what kind +of project you already have, installs the matching PHARN capabilities from +[`pharn-dev/pharn-oss`](https://github.com/pharn-dev/pharn-oss), and records the install in +`pharn.config.json` and `pharn.records.json`. ## Why use it? -AI agents can move fast, but a fast diff without durable context is hard to -trust. PHARN is built around a simple idea: the reasoning behind a change should -be committed beside the change. - -- **Preserve intent.** Specs, plans, constraints, and review notes live in the - repository, not only in an agent transcript. -- **Make work inspectable.** PHARN installs grillers and lenses: pipeline - checks and review perspectives that help interrogate a plan or diff before - it ships. -- **Keep updates safe.** `pharn update` uses per-file hashes to avoid - overwriting local edits unless you explicitly choose `--force`. -- **Stay tool-shaped, not service-shaped.** The CLI fetches open content, - copies files into your project, and leaves the state in version-controlled - markdown and JSON. +AI agents can move fast, but a fast diff without durable context is hard to trust. PHARN is built around a +simple idea: the reasoning behind a change should be committed beside the change. -## Quick start - -Run PHARN inside an existing git project: +- **Preserve intent.** Specs, plans, constraints, and review notes live in the repository, not only in an + agent transcript. +- **Make work inspectable.** PHARN installs grillers and lenses: pipeline checks and review perspectives + that help interrogate a plan or diff before it ships. +- **Keep updates safe.** `pharn update` uses per-file hashes to avoid overwriting local edits unless you + explicitly choose `--force`. +- **Stay tool-shaped, not service-shaped.** The CLI fetches open content, copies files into your project, + and leaves the state in version-controlled markdown and JSON. -```bash -npx @pharn-dev/pharn@latest init -``` +## Quick start -For a new app, make sure it is a git repository before installing PHARN. -`create-next-app` already runs `git init` and makes the first commit (unless git -is missing or you pass `--disable-git`), so initialize git only when `.git` is -absent: +Run PHARN inside an existing git project. For a new app, make sure it is a git repository first +(`create-next-app` already runs `git init` and commits, unless git is missing or you pass `--disable-git`): ```bash -npx create-next-app@latest my-app -cd my-app +npx create-next-app@latest my-app && cd my-app [ -d .git ] || { git init && git add -A && git commit -m "init"; } npx @pharn-dev/pharn@latest init ``` -After install, open Claude Code in the project and start with: - -```text -/pharn-spec -``` - -Or run the whole chain in one command: - -```text -/pharn-loop implement password reset with a one-time token -``` +Then open Claude Code and start with `/pharn-spec`, or run the whole chain with +`/pharn-loop implement password reset with a one-time token`. Either way the run begins at the spec: +`/pharn-plan` halts unless an **Approved**, un-drifted `SPEC.md` exists ([walkthrough](docs/getting-started.md)). -Either way the run begins at the spec, and it has to: `/pharn-plan` enforces a -deterministic input gate and halts unless an **Approved**, un-drifted `SPEC.md` -already exists, so there is no entry point further down the chain. The exact -command files come from the `pharn-dev/pharn-oss` version installed into your -repo. - -**Your project needs a test runner with per-test results.** The `test` stage -writes each acceptance criterion's test before any code exists and requires it -to fail, so it needs a `test` script (plus `test:e2e` or `e2e` for end-to-end -criteria) whose reporter writes per-test JSON, named under `testResults` in -`pharn.config.json`. Without one, `/pharn-test` stops and asks, and -`/pharn-loop` ends with `blocked: no-test-runner`. A fresh app like the -`create-next-app` one above has no `test` script, so set the runner up first, -as its own increment (a SPEC with `spec_kind: test-infra`). Setup is in -upstream's +**Your project needs a test runner with per-test results.** The `test` stage writes each acceptance +criterion's test before any code exists and requires it to fail, so it needs a `test` script (plus +`test:e2e` or `e2e` for end-to-end criteria) whose reporter writes per-test JSON, named under +`testResults` in `pharn.config.json`. Without one, `/pharn-test` stops and asks, and `/pharn-loop` ends +with `blocked: no-test-runner`. A fresh `create-next-app` has no `test` script, so set the runner up +first, as its own increment (a SPEC with `spec_kind: test-infra`); see upstream's [Per-test results](https://github.com/pharn-dev/pharn-oss#per-test-results). ## How it works -`pharn init` is archetype-driven. There is no stack questionnaire and no module -catalog. +`pharn init` is archetype-driven. There is no stack questionnaire and no module catalog. -| Step | What happens | -| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Detect | Reads `package.json` dependency names and performs a bounded, symlink-safe file-tree scan to classify the project as `ssr`, `backend`, `spa`, `lib`, or a combination. | -| Fetch | Resolves the newest **verified release** of `pharn-dev/pharn-oss` (a tag pharn-oss creates only after its post-merge CI passed) to its commit, downloads that commit's codeload tarball, extracts it into a temp directory, and checks its `SKILLS_VERSION` matches the tag. With no release resolvable it exits 1 and names `--ref main`, never falling back to the tip ([details](docs/troubleshooting.md#no-verified-release-could-be-resolved)). `--ref main` installs the tip of `main` instead, for contributors. | -| Resolve | Selects capabilities whose `applies` value is `universal` or intersects your detected archetypes. Skipped capabilities are named with the reason. | -| Install | Copies the selected capabilities plus fixed PHARN product surfaces into your repo, mirroring the upstream layout. | -| Record | Writes `pharn.config.json` and `pharn.records.json` so future updates can tell PHARN-owned files from local edits. | - -The install layout places most runtime surfaces under `pharn/` and Claude Code -integration under `.claude/`. The legacy flat layout (everything at the project -root) was removed in v0.21.0: a project still recorded at it is asked to re-run -`pharn init`, which reinstalls at `pharn/` and leaves the old top-level copies -for you to delete ([support policy](docs/support-policy.md)). +| Step | What happens | +| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Detect | Reads `package.json` dependency names and a bounded, symlink-safe file-tree scan to classify the project as `ssr`, `backend`, `spa`, `lib`, or a combination ([rules](docs/commands/init.md#3-detect-archetypes)). | +| Fetch | Downloads the newest **verified release** of `pharn-dev/pharn-oss` (a tag created only after its post-merge CI passed). With none resolvable it exits 1 and names `--ref main`, never falling back to the tip ([details](docs/troubleshooting.md#no-verified-release-could-be-resolved)). | +| Resolve | Selects capabilities whose `applies` value is `universal` or intersects your archetypes. Skipped capabilities are named with the reason. | +| Install | Copies the selected capabilities plus the fixed PHARN product surfaces into `.claude/` and `pharn/`. | +| Record | Writes `pharn.config.json` and `pharn.records.json` so future updates can tell PHARN-owned files from local edits. | ## What gets installed -| Artifact | Purpose | -| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| `pharn/pharn-pipeline/grillers//`, `pharn/pharn-review//` | Pipeline grillers and review lenses selected for your project archetype(s). | -| `.claude/commands/`, `.claude/hooks/` | The installed `/pharn-*` Claude Code slash commands and deterministic `.cjs`/`.mjs` hooks. | -| `.claude/agents/` | The `pharn-review-lens` subagent each `/pharn-review` lens runs in (pharn-oss 6.64.0+). | -| `pharn/pharn-contracts/`, `pharn/floor/` | Schemas shared across PHARN stages and floor checkers invoked by the workflow. | -| `pharn/pharn-core/` | Agent-readable mechanism skills, including the seam resolver. | -| `pharn/CONSTITUTION.md`, `pharn/ARCHITECTURE.md` | Trusted PHARN docs copied from upstream in the current layout. | -| `pharn/THREAT-MODEL.md`, `pharn/LIMITS.md` | The other two trusted docs. | -| `pharn/LICENSE` | PHARN's Apache-2.0 license copy. Your root `LICENSE` is never overwritten. | -| `pharn/features/README.md` | The feature-loop boundary contract referenced by installed commands. | -| `pharn.config.json` | Installed version, commit, layout, archetypes, capabilities, and defaults. | -| `pharn.records.json` | Per-file hashes for drift-safe updates. Commit this with the config. | - -An existing `.claude/settings.json` is preserved. PHARN may create it when -absent, but it never overwrites your Claude Code settings. - -As you run the workflow, PHARN writes one directory per increment — -`pharn/features//` — holding that increment's `SPEC.md`, `PLAN.md`, -`AC-TESTS.md`, `GRILL.md`, `BUILD.md`, `REGRESSION.md`, `VERIFY.md`, then -`SHIP.md` + `BRIEFING.md` (`/pharn-ship`) or `LOOP.md` (`/pharn-loop`), a -`RUN-REPORT.md`, and the machine-readable records beside them -(`AC-TESTS.lock.json`, `cost.json`, the `*-report.json` files). Those are the -durable record; commit them. `pharn/.run/` (runtime scratch; `.pharn/` before -pharn-oss 7.0.0) and `pharn/.backup/` (see [Safety model](#safety-model)) are not: -`pharn init` and `pharn update` append them to your `.gitignore` (creating it if -needed) unless it already covers them — in any common spelling, such as -`/pharn/.run`, `pharn/.run/**` or a negation `!pharn/.run/` you wrote on purpose. -They only ever append: your lines are never reordered or rewritten, CRLF stays -CRLF, and a second run changes nothing. A symlinked `.gitignore` is never written -through (you get a warning naming the lines). Lines added to `.gitignore` do not -untrack files you already committed (`git rm -r --cached pharn/.run` does). -`pharn/.lock*` is a transient file — add it yourself if you like. A `.pharn/` -line left from an install older than pharn-oss 7.0.0 is neither rewritten nor -mentioned; replace it with `pharn/.run/` yourself. - -Everything PHARN keeps in your project lives under `.claude/` and `pharn/`, plus -the two JSON files at the root. An install made from a pharn-oss older than 7.0.0 -also has `THREAT-MODEL.md` and `LIMITS.md` at the root, and may have -`memory-bank/` and `pharn.spec-template.md` there. pharn-oss 7.x reads none of -them. `pharn update` installs the `pharn/` copies of the two docs and lists the -root copies it recorded under `ORPHANED`, for you to delete. It never moves, -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) 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, -recorded as `skillsVersion` in `pharn.config.json` and taken from upstream's -`SKILLS_VERSION`. They move independently, and `pharn status` / `pharn update` -are keyed to the latter. +Everything PHARN keeps in your project lives under `.claude/` (commands, hooks, agents) and `pharn/` +(capabilities, contracts, core, floor checkers, the trusted docs, a `LICENSE` copy and the features README), +plus `pharn.config.json` and `pharn.records.json` at the root: commit both. The full table is in +[Getting started: What you get](docs/getting-started.md#what-you-get). An existing `.claude/settings.json` +is never overwritten. As you run the workflow, PHARN writes one directory per increment, +`pharn/features//`, which is the durable record; commit it. `pharn init` and `pharn update` add +`pharn/.run/` and `pharn/.backup/` to your `.gitignore` ([how](docs/commands/init.md#gitignore)). + +**Two version numbers, on purpose.** The npm package `@pharn-dev/pharn` carries the installer's version. +The content it installs carries its own, recorded as `skillsVersion` in `pharn.config.json` and taken from +upstream's `SKILLS_VERSION`. They move independently, and `pharn status` / `pharn update` are keyed to the +latter. ## After install -Three things about the installed hooks are worth knowing on day one. - -**Hooks enforce only once they are registered in `.claude/settings.json`.** If -your project already had that file, PHARN preserved it instead of overwriting -it and printed a `HOOKS` note listing each hook it does not wire, as -paste-ready JSON — until you copy those entries across, every guarantee that -depends on a `PreToolUse` hook is inactive, and `pharn status --strict` fails. - -**Once wired, the default depends on your tree (pharn-oss 6.24.0+).** With no -active scope, `enforce-writes-scope.cjs` applies that default. - -In an **installed** project (`pharn.config.json` carries a non-empty -`skillsVersion`), you can edit ordinary application source **outside** an open -PHARN run. The narrow fail-closed posture — Claude Code's -Write/Edit/MultiEdit/NotebookEdit tools restricted to `pharn/features/**` and -`pharn/.run/**` — applies **only while** `/pharn-ship`, `/pharn-loop`, or -`/pharn-review` has an open marker (`pharn/.run///active.json`; -ship and review via `pharn/floor/run-marker.mjs`, loop via -`require-loop-record.cjs`). Outside those runs the guard **denies** PHARN's -installed surface (`pharn/**` except `pharn/features/**` and `pharn/.run/**`, -`.claude/**`, `pharn.config.json`, and `pharn/.run/writes-scope.json`) and -**allows** the rest of your project, including app source. While a stage is -running it still sets explicit scope from the concrete paths your `PLAN.md` -declared. - -In PHARN's own dev repo or an unsignalled tree, the pre-6.24.0 posture -remains: fail-closed everywhere with no active scope. Clearing the scope -(`set-writes-scope.cjs --clear`, or deleting `pharn/.run/writes-scope.json`) -returns to whichever default your tree and open-run state compute; it does not -by itself re-open source in those postures, or during an open install run. - -Writes issued through Bash bypass both write guards entirely. - -**`/pharn-loop` has a `Stop` guard too.** `require-loop-record.cjs` is not a -write guard: while an unattended `/pharn-loop` run has written no `LOOP.md`, it -refuses to let the turn end, a bounded number of times, and it fails open. It -also does nothing until registered — under `Stop`, with no matcher. The -`settings.json` upstream ships has registered it since pharn-oss 6.12.0, but a -file PHARN preserved, or one created by an earlier install, lacks the entry: -copy it across by hand. `pharn update` never edits `.claude/settings.json`; -`pharn init`, `pharn status` and `pharn update` name the missing entry in a -`HOOKS` note. - -The full set of bounds lives in upstream's -[`LIMITS.md`](https://github.com/pharn-dev/pharn-oss/blob/main/LIMITS.md) and -[README](https://github.com/pharn-dev/pharn-oss#readme). +- **Hooks enforce only once they are registered in `.claude/settings.json`.** If your project already had + that file, PHARN kept it and printed a `HOOKS` note listing each hook it does not wire, as paste-ready + JSON. Until you copy them across, the guarantees that depend on a `PreToolUse` hook are inactive, and + `pharn status --strict` fails. +- **`/pharn-loop` has a `Stop` guard** (`require-loop-record.cjs`) that also does nothing until it is + registered under `Stop`. `pharn init`, `pharn status` and `pharn update` name a missing entry. +- **`pharn update` never edits `.claude/settings.json`**, so copy new hook entries across by hand. Writes + issued through Bash bypass the write guards entirely. + +What the write guards allow and deny, and the full set of bounds, are in upstream's +[README](https://github.com/pharn-dev/pharn-oss#what-gets-installed) and +[`LIMITS.md`](https://github.com/pharn-dev/pharn-oss/blob/main/LIMITS.md). ## Day-to-day workflow -Once PHARN is installed, use the slash commands from Claude Code. The pipeline -is eight typed stages, each reading what the previous one produced: - -| Stage | Command | Purpose | -| ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| Spec | `/pharn-spec` | Capture feature intent and scope. Stops for your approval. | -| Plan | `/pharn-plan` | Turn the approved spec into an implementation plan, mapping each acceptance criterion to a test (`AC-TESTS.md`). | -| Grill | `/pharn-grill` | Challenge the plan before code is written. | -| Test | `/pharn-test` | Write each acceptance criterion's test before the build, run it, and require it to fail. `/pharn-build` refuses to start without that evidence. | -| Build | `/pharn-build` | Implement an approved increment. | -| Regress | `/pharn-regress` | Look for regressions outside the just-built feature. | -| Verify | `/pharn-verify` | Verify behavior and PHARN floor requirements, including that every acceptance criterion's test now passes. | -| Ship | `/pharn-ship` | Run stages 1-7 in order, then stop at the merge/fix/abandon gate. | - -`/pharn-ship` is itself the eighth stage: it orchestrates the seven before it in -one pass, so you rarely run them by hand, and it keeps both human gates — -approve the spec before code is written, decide merge/fix/abandon after -verification. `/pharn-loop` runs that same chain unattended: the model approves -the spec, iterates build -> regress -> verify until green, an iteration cap, or -a terminal failure, commits a green result to a new local branch (never pushed -or merged), and leaves the merge/fix/abandon decision to you after the run. -From pharn-oss 7.7.0, a full `/pharn-loop` (not `--quick`) also runs -`/pharn-triage` after the grill: it gives every grill finding one disposition. -Since 7.8.0 a `replan` verdict sends the run back to `/pharn-plan` for at most -two re-plan rounds, and since 7.9.0 a verdict that still escalates goes to -`/pharn-supervise`, a fresh agent that decides `stop` or `proceed-at-risk` (the -escalated findings are then named as known risk in the green commit and the run -report); since 7.10.0 it may instead amend the SPEC once per run (`amend-spec`). -That decision is one model's judgment, not a check. You can run `/pharn-triage` -yourself after a full `/pharn-grill`. - -`/pharn-spec` fills PHARN's default SPEC template, or your own if you put one at -`pharn/spec-template.md`. The write guard denies Claude -Code's edit tools on that path, so edit it yourself; see upstream's -[Your own SPEC template](https://github.com/pharn-dev/pharn-oss#your-own-spec-template). - -Two commands sit outside the pipeline: - -| Command | Purpose | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `/pharn-review` | Run the review lenses in parallel over any code and merge their findings deterministically. Standalone — no pipeline stage invokes it. | -| `/pharn-memory-promote` | Promote one lesson into `pharn/memory-bank/` through a gated provenance check. | +Once PHARN is installed, use the slash commands from Claude Code. The pipeline is eight typed stages, each +reading what the previous one produced ([what each does](docs/getting-started.md#after-init)). +`/pharn-ship` runs the first seven in one pass and keeps both human gates: approve the spec before code is +written, decide merge/fix/abandon after verification. `/pharn-loop` runs the same chain unattended and +commits a green result to a new local branch (never pushed or merged), leaving the merge decision to you. Outside the pipeline, +`/pharn-review` runs the review lenses over any code, and `/pharn-memory-promote` promotes one lesson into +`pharn/memory-bank/`. `/pharn-spec` uses your own SPEC template if you put one at `pharn/spec-template.md` +(see upstream's [Your own SPEC template](https://github.com/pharn-dev/pharn-oss#your-own-spec-template)). ## CLI commands @@ -311,162 +150,75 @@ Two commands sit outside the pipeline: | `pharn --help` | Show every command, option and environment variable. `pharn --help` shows one command and only the options it takes. | | `pharn --version` | Show the installed CLI version. | -`init` also takes `--archetype ` (for example `--archetype backend` or -`--archetype ssr,backend`) to install for those archetypes instead of the -detected ones — the in-product correction for a misdetected project. The value -must be a comma-separated list of `ssr`, `backend` and `spa`, or `lib` alone, -each at most once; anything else exits 1. The choice is recorded, so `update` -keeps it. The install summary shows what triggered each detected archetype -(`backend ← src/app/api/`), or that they came from the flag. - -Three behaviours matter if you script the CLI: - -- **Options are per-command.** Passing one a command does not take prints - ``Unsupported option for `status`: "--force"`` to stderr with ``Run `pharn --help` for usage.`` - and exits **1**; an extra positional is refused the same way. Both previously - parsed, were silently dropped, and exited 0. -- **`init` and `update` prompt.** Off a TTY a plain run exits 1 rather than - prompting into a dead stream. `update --yes` is the way through in CI. For - `init`, `--yes` skips the summary confirm but never the overwrite one: it - installs only into a project where none of its files exists yet, and - otherwise exits 1 — so a re-install always refuses it (use `update`). Both - commands' `--dry-run` needs no terminal and writes nothing. `uninstall` - likewise exits 1 off a TTY unless it is given `--yes`. -- **One writer at a time.** `init`, `add`, `remove`, `update` and `uninstall` - take an advisory lock at `pharn/.lock`; a second run refuses rather than - queueing. `add`, `remove`, `update` and `uninstall` also re-read - `pharn.config.json` once they hold the lock, and refuse — writing nothing — - if another run changed it after they read it (for example while a confirm - prompt was open). - `list` and `status` never take it and are never blocked by one, so - `pharn status --strict` stays runnable in CI while an update is in flight. +`init` also takes `--archetype ` (for example `--archetype ssr,backend`) to install for those +archetypes instead of the detected ones; the choice is recorded, so `update` keeps it. -## Agent skills +If you script the CLI: an option a command does not take, or an extra positional, exits **1** +(``Unsupported option for `status`: "--force"``); off a TTY a plain `init`, `update` or `uninstall` exits 1 +(`update --yes` is the CI line; `init --yes` never confirms an overwrite; `--dry-run` needs no terminal); +and one writer at a time holds `pharn/.lock`, while `list` and `status` never take it, so +`pharn status --strict` stays runnable in CI. A config changed while a prompt was open refuses the write. -If you would rather ask than remember flags, the -[`pharn-dev/skills`](https://github.com/pharn-dev/skills) repository ships a -`pharn-cli` skill that operates this CLI for you. Ask your agent "Is PHARN up to -date in this project?" or "What would an update change?" and it runs the -read-only checks and a `--dry-run` preview first, applies the update without -overwriting your edits, and adds or removes grillers and lenses. The same -repository also carries `phargus` skills for setting up and diagnosing Node.js -applications with [Phargus](https://github.com/pharn-dev/phargus). - -In Claude Code: - -```text -/plugin marketplace add pharn-dev/skills -/plugin install pharn@pharn-dev -``` +## Agent skills -Or with the Skills CLI: `npx skills add pharn-dev/skills --skill pharn-cli`. -The skills are optional; every command above works without them. +The [`pharn-dev/skills`](https://github.com/pharn-dev/skills) repository ships a `pharn-cli` skill that +operates this CLI for you: ask "Is PHARN up to date in this project?" or "What would an update change?" and +it runs the read-only checks and a `--dry-run` first, applies updates without overwriting your edits, and +adds or removes grillers and lenses. It also carries `phargus` skills for +[Phargus](https://github.com/pharn-dev/phargus). In Claude Code, run `/plugin marketplace add pharn-dev/skills` +then `/plugin install pharn@pharn-dev`, or use `npx skills add pharn-dev/skills --skill pharn-cli`. The skills +are optional. ## Safety model PHARN is intentionally conservative about writes: -- `init` checks for existing install targets and asks before overwriting them, - 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. 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. Every delete, and what - is never deleted: [What PHARN deletes](docs/reference/deletes.md). -- `update --force` backs up overwritten files under `pharn/.backup//` - before writing. `add` does the same for any destination file that differs from - upstream, and refuses the whole install — writing nothing — when a destination - path crosses a symlinked directory. +- `init` checks for existing install targets and asks before overwriting them, 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. 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. Every delete, and what is never deleted: [What PHARN deletes](docs/reference/deletes.md). +- `update --force` backs up overwritten files under `pharn/.backup//` before writing. `add` does + the same for any destination file that differs from upstream, and refuses the whole install (writing + nothing) when a destination path crosses a symlinked directory. - `status` and `list` are read-only. -- `remove` deletes only the selected capability directory and prunes its records, - after backing up to `pharn/.backup//` any file in it that `pharn` - cannot prove it wrote unchanged; - it never touches `CONSTITUTION.md`, `pharn/memory-bank/`, or your detected - archetypes, and refuses when that directory's path crosses a symlink. -- `uninstall` deletes only files recorded in `pharn.records.json` that still - match their recorded hash, inside `pharn`'s install paths; it keeps every file - you changed or added and lists the ones it kept, backs up `pharn.config.json` - before deleting it, never writes `.claude/settings.json` (it prints the hooks - you need to unwire instead), and refuses — deleting nothing — without a usable - record store. - -PHARN can also refuse to install at all: if upstream declares a minimum CLI -version newer than yours, `init`/`add`/`update` stop with a named error before -writing anything. - -Remote content is treated as untrusted input. Capability names, copyable file -names, versions, commit SHAs, and paths are validated against strict allowlists; -path traversal and symlink escapes are rejected; copied file contents are not +- `remove` deletes only the selected capability directory and prunes its records, after backing up to + `pharn/.backup//` any file in it that `pharn` cannot prove it wrote unchanged; it never touches + `CONSTITUTION.md`, `pharn/memory-bank/`, or your detected archetypes, and refuses when that directory's + path crosses a symlink. +- `uninstall` deletes only files recorded in `pharn.records.json` that still match their recorded hash, + inside `pharn`'s install paths; it keeps every file you changed or added and lists the ones it kept, backs + up `pharn.config.json` before deleting it, never writes `.claude/settings.json` (it prints the hooks you + need to unwire instead), and refuses (deleting nothing) without a usable record store. + +PHARN can also refuse to install at all: if upstream declares a minimum CLI version newer than yours, +`init`/`add`/`update` stop with a named error before writing anything. Remote content is treated as +untrusted input. Capability names, copyable file names, versions, commit SHAs, and paths are validated +against strict allowlists; path traversal and symlink escapes are rejected; copied file contents are not executed by the CLI. ## Current scope -PHARN is intentionally scoped: - -- It targets **Claude Code today**. Codex and Cursor support are planned, not - shipped. -- It requires a git-initialized project and **Node >= 24.2.0**, for the CLI - (`@pharn-dev/pharn`, `engines.node`) and for the **installed floor** - (`pharn/floor/*.mjs`) alike. The floor's checkers gate on `import.meta.main`; - on an older Node a guarded tool used to exit 0 without running its checks, so - they now refuse to run there (one stderr line, exit 2). `pharn init` and - `pharn update` therefore refuse up front on an older Node, with nothing - written, and `pharn status` prints the floor beside the Node you are running. - CI runs on Node 24, and a smoke job starts the packed CLI on exactly 24.2.0. -- **Archetype detection is JS/TS-shaped.** The signals are `package.json` - dependency names, `.tsx`/`.jsx` files, and — in a Next.js app only — - `next.config.*`, `app/` route handlers and `app/api`/`pages/api`. A root - `api/`, a `migrations/` directory and `.sql` files in a database directory - count only when the project has a root `package.json`. A Python, Go, Rust, - Ruby or PHP repo without one produces no signal, resolves to `lib`, and - receives the universal capabilities only — a correct outcome, not a failure. - One that also has a root `package.json` (a Vite frontend, or tooling only) - can resolve `backend` from its migrations; `pharn init --archetype` corrects - either way. -- **Server and database packages count only as runtime dependencies.** A - runtime database driver dependency (`pg`, `mongodb`, an ORM) means `backend`, - like a server framework; the same package only in `devDependencies` (a mock - server, a test database) does not. A backend bundled so that its framework is - only a devDependency needs `pharn init --archetype backend`. SSR and UI - frameworks count from `devDependencies` too. -- **Detection is bounded.** The file-tree scan examines at most 50,000 entries, - 24 directories deep (skipped directories such as `node_modules` do not - count). When it stops at a bound before its result is settled, the install - summary says `detection stopped early` and `init --dry-run --json` reports - `"detectionTruncated": true`; check the archetypes and pass `--archetype` if - they are wrong. -- It does not scaffold your application or install framework packages. -- It does not replace tests, human review, or release judgment. It gives those - 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). `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. - `--json` reports stay additive within `schemaVersion: 1` - ([JSON output](docs/reference/json-output.md)). Compatibility code - for older installs is removed on a named version: see the - [support policy](docs/support-policy.md). - -See the [roadmap](docs/roadmap.md) for shipped versus planned work. +- It targets **Claude Code today**. Codex and Cursor support are planned, not shipped. +- It requires a git-initialized project and **Node >= 24.2.0**, for the CLI and for the installed floor + checkers (`pharn/floor/*.mjs`), which refuse to run on an older Node. `pharn init` and `pharn update` + refuse up front on an older Node, with nothing written. +- **Archetype detection is JS/TS-shaped and bounded.** A Python, Go, Rust, Ruby or PHP repo without a root + `package.json` resolves to `lib` and gets the universal capabilities, a correct outcome; `pharn init +--archetype` corrects any misdetection. The rules: [Detect archetypes](docs/commands/init.md#3-detect-archetypes). +- It does not scaffold your app, install framework packages, or replace tests, review or release judgment. +- **Supported installs: the current minor and the previous one.** Re-run `pharn init` on an older install; + it keeps the capabilities you added. `--json` reports stay additive within `schemaVersion: 1`. See the + [support policy](docs/support-policy.md) and the [roadmap](docs/roadmap.md). ## Documentation -Start here: [docs/](docs/README.md) - -- [Getting started](docs/getting-started.md) -- [Command reference](docs/README.md#commands) -- [pharn.config.json](docs/reference/pharn-config.md) -- [pharn.records.json](docs/reference/pharn-records.md) -- [Support policy](docs/support-policy.md) -- [Troubleshooting](docs/troubleshooting.md) -- [Roadmap](docs/roadmap.md) +Start here: [docs/](docs/README.md). [Getting started](docs/getting-started.md) · +[Commands](docs/README.md#commands) · [pharn.config.json](docs/reference/pharn-config.md) · +[pharn.records.json](docs/reference/pharn-records.md) · [Support policy](docs/support-policy.md) · +[Troubleshooting](docs/troubleshooting.md) · [Roadmap](docs/roadmap.md) ## Development @@ -474,34 +226,21 @@ Start here: [docs/](docs/README.md) npm install npm run dev -- init npm run build -npm run test -npm run check +npm run check # format:check, lint, lint:md, typecheck, test ``` -Useful scripts: - -| Script | Purpose | -| ----------------------------- | ----------------------------------------------------- | -| `npm run typecheck` | Type-check source and tests. | -| `npm run lint` | Run ESLint with zero warnings. | -| `npm run lint:md` | Run markdownlint over docs and root markdown. | -| `npm run test:coverage` | Run the Vitest coverage gate used by CI. | -| `npm run build:install-local` | Build and install the local CLI into local test apps. | - -Set `PHARN_DEBUG=1` for verbose fetch and install errors; `NO_COLOR` / `FORCE_COLOR` -control colour (see [Colour](docs/troubleshooting.md#colour)). See +Other scripts: `npm run test:coverage` (the coverage gate CI runs) and `npm run build:install-local` (build +and install the local CLI into local test apps). Set `PHARN_DEBUG=1` for verbose fetch and install errors; +`NO_COLOR` / `FORCE_COLOR` control colour (see [Colour](docs/troubleshooting.md#colour)). See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor notes and release discipline. ## Security -The CLI has a small trust boundary: it downloads PHARN content from GitHub, -validates and extracts it, then copies selected files into your project. The -security-sensitive path validation, tar extraction, symlink handling, and update -decision tables are covered by tests. - -Please report vulnerabilities through [SECURITY.md](SECURITY.md), not public -issues. The detailed model is in [THREAT-MODEL.md](THREAT-MODEL.md) and -[LIMITS.md](LIMITS.md). +The CLI has a small trust boundary: it downloads PHARN content from GitHub, validates and extracts it, then +copies selected files into your project. The security-sensitive path validation, tar extraction, symlink +handling, and update decision tables are covered by tests. Please report vulnerabilities through +[SECURITY.md](SECURITY.md), not public issues. The detailed model is in [THREAT-MODEL.md](THREAT-MODEL.md) +and [LIMITS.md](LIMITS.md). ## License diff --git a/docs/README.md b/docs/README.md index 4475e041..42702383 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,6 +26,8 @@ The CLI version (`pharn --version`) and the content version it installs (`skills - [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 +- [update: less common situations](reference/update-advanced.md) — the executable unit, orphans, the `models` block, unreadable or missing files, and the other states most `pharn update` runs never meet +- [The project lock](reference/project-lock.md) — `pharn/.lock`: who takes it, why, and when a stale one is broken - [Support policy](support-policy.md) — which installs and `pharn` versions are supported, and what is being retired when ## Other diff --git a/docs/commands/add.md b/docs/commands/add.md index eb6c8f77..7cde9ff7 100644 --- a/docs/commands/add.md +++ b/docs/commands/add.md @@ -94,7 +94,7 @@ Run [`pharn update`](update.md) to bring your install to the current version, th **Kept local edits.** If `pharn update` skipped files **only because you edited them** (`modified` / `unrecorded`), it leaves `skillsVersion` at the old value but records the version it applied as `pendingSkillsVersion` in `pharn.config.json`. That includes an update that -[held the executable unit](update.md#the-executable-unit-is-upgraded-all-or-none) because of your +[held the executable unit](../reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none) because of your edit: the floor, hooks and `pharn-*` commands stay at the old version, and every other file you did not edit is at the new one. `add` accepts a clone at that version too, because it writes capability directories only, and it still does not advance `skillsVersion` or `commit`. If upstream has moved on diff --git a/docs/commands/init.md b/docs/commands/init.md index 21b90fcd..0a37355d 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -278,6 +278,13 @@ Router framework mode's templates list them there — and the summary cites them not read. React Router v7 framework mode, TanStack Start, SolidStart, Qwik City, Analog and Vike are recognized as `ssr`; React Router in library mode (`react-router` alone) is `spa`. +In a monorepo or workspace, detection runs from the current directory: it reads the `package.json` there, +never walks up to a workspace root, and does not read the workspace packages' own `package.json` files, so a +framework only a package's `package.json` names is not seen (pass it with `--archetype`). The tree walk does +reach `apps/` and `packages/`, as the table above says. Run `pharn init` from the directory that holds both +`.git` and the app's `package.json`; split layouts (`.git` at the root, the app's `package.json` in +`apps/web/`) are unsupported. + The tree walk examines at most 50,000 entries, 24 directories deep (the skipped directories above cost nothing), in sorted name order, and stops early once an `ssr` and a `backend` signal are both found — nothing more could change the result. When it reaches a bound before that, the summary adds @@ -287,7 +294,7 @@ cost nothing), in sorted name order, and stops early once an `ssr` and a `backen So an Angular, Vue or RTK Query `src/app/`, or a library's Next.js docs site in `website/`, no longer reads as a server, and a Python, Go, Rust, Ruby or PHP project's migrations no longer read as a -JavaScript backend — those projects have no root `package.json`. One that does (a Laravel or Rails app +JavaScript backend — those projects have no root `package.json` (the backend capabilities PHARN ships match JavaScript/TypeScript code). One that does (a Laravel or Rails app with a Vite frontend, or a `package.json` kept only for tooling) still resolves `backend` from its migrations; correct it with `--archetype`. Only names are tested against fixed in-code allowlists — no discovered file body is read (other than `package.json`, which must be a regular file of at most 4 MiB — a leading UTF-8 BOM is ignored; anything else counts as no `package.json`) and no untrusted value is executed, interpolated, or logged. @@ -391,7 +398,7 @@ Capabilities you added by hand with `pharn add` (`source: "manual"` in `pharn.co too — as long as upstream still ships them. The summary lists them as "added by hand". One that upstream no longer ships is dropped from `pharn.config.json` and named. See [Dropped capabilities are deleted](#dropped-capabilities-are-deleted) for what happens to its directory. A capability -upstream still ships but this pharn [cannot read](update.md#when-pharn-cannot-read-a-capability-upstream) +upstream still ships but this pharn [cannot read](../reference/update-advanced.md#when-pharn-cannot-read-a-capability-upstream) is **left as it is**, however it was added: its config entry, files and records are untouched, and it is listed in `frozenCapabilities` so the next [`pharn update`](update.md) re-checks it. Top-level keys in `pharn.config.json` that pharn does not own, such as upstream's `testResults` and `ship`, are copied @@ -409,7 +416,7 @@ commands name the problem), and re-run. Otherwise the overwrite prompt that foll `pharn.config.json` and defaults to No. `init --yes` refuses any existing config before it downloads anything, so it never gets as far as the summary. If `pharn.config.json` changes while `init` waits at its prompts (edited by hand or by another program — no other `pharn` command can write it while `init` -holds the lock), `init` refuses and writes nothing; re-run it. The target set is the fetched clone's `pharn-install.json` + your resolved selection (`lib/install-manifest.ts`), so it is exact — not a git-history heuristic. +holds the lock), `init` refuses and writes nothing; re-run it. The target set is the fetched clone's `pharn-install.json` plus your resolved selection, so it is exact — not a git-history heuristic. **When `init` refuses to install.** After you choose **install**, and before it asks to overwrite anything, `init` checks every path it is about to write and stops, naming each problem, if the copy diff --git a/docs/commands/remove.md b/docs/commands/remove.md index 2fac8a80..12fe3360 100644 --- a/docs/commands/remove.md +++ b/docs/commands/remove.md @@ -50,10 +50,7 @@ removed in v0.21.0, is refused with a message to re-run `pharn init`.) Removal i `pharn remove --yes` is **refused** (exit 1) rather than accepted and ignored. There is nothing here for it to skip: the named form above deletes without asking, and the picker's one confirmation is the destructive gate itself — it is always shown, it lists exactly what will be deleted, and it defaults -to **No**. - -> Earlier releases accepted `pharn remove --yes` and silently dropped it. See -> [Unsupported option for this command](../troubleshooting.md#unsupported-option-for-this-command). +to **No**. See [Unsupported option for this command](../troubleshooting.md#unsupported-option-for-this-command). ## What is backed up before the delete diff --git a/docs/commands/status.md b/docs/commands/status.md index 654307d6..f324e70e 100644 --- a/docs/commands/status.md +++ b/docs/commands/status.md @@ -122,7 +122,7 @@ 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 +`UNREADABLE`, that `pharn update` prints (see [update](../reference/update-advanced.md#orphaned-files) for what each group 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. @@ -258,7 +258,7 @@ Nothing is written on any of these paths — `status` still never writes, delete One case is worth knowing before you wire `--strict` into CI: when a new `pharn` release begins installing a surface earlier releases did not, an existing install is genuinely missing those files and `--strict` goes red until a plain `pharn update` restores them, at the same skills version too. See -[a surface added by a newer CLI](update.md#a-surface-added-by-a-newer-cli-at-the-same-skills-version). +[a surface added by a newer CLI](../reference/update-advanced.md#missing-files-at-the-same-skills-version). ## Related diff --git a/docs/commands/update.md b/docs/commands/update.md index b19872da..8e86c655 100644 --- a/docs/commands/update.md +++ b/docs/commands/update.md @@ -14,14 +14,10 @@ pharn update --ref latest # follow verified releases instead of main (recorded pharn update --ref main # back to the tip of main (recorded) ``` -`--force`, `--yes`/`-y`, `--ref`, `--dry-run`, `--json` and `--compact` are `update`'s **only** options, -and they compose. Two imply others: `--json` implies `--dry-run`, so `pharn update --json` is -`pharn update --dry-run --json`, and `--compact` implies `--json` (and so `--dry-run`), so -`pharn update --compact` is `pharn update --dry-run --json --compact`. Any other option — `--strict`, -`--no-drift` — is refused with ``Unsupported option for `update` `` on stderr and exit **1**, as is an -extra positional. So is a value on an on/off option (`--json=false`: `Option takes no value`), a negated -option (`--no-dry-run`: `Unknown option`) and a second `--ref` (`Repeated option`). See -[Unsupported option for this command](../troubleshooting.md#unsupported-option-for-this-command). +These are `update`'s **only** options, and they compose: `--json` implies `--dry-run`, and `--compact` +implies `--json`. Any other option, an extra positional, a value on an on/off option (`--json=false`), a +negated option (`--no-dry-run`) or a second `--ref` exits **1** with one stderr line (see +[Unsupported option for this command](../troubleshooting.md#unsupported-option-for-this-command)). `update` compares every PHARN-owned file against the per-file hashes recorded when it was installed ([`pharn.records.json`](../reference/pharn-records.md)). A file whose bytes are exactly what `pharn` @@ -29,83 +25,55 @@ wrote is upgraded. A file it cannot prove is untouched is **skipped and listed** ## Behavior -1. Checks the Node version before anything else: PHARN's installed floor checkers refuse to run below - **Node 24.2.0**, so on an older Node (or one whose version cannot be read) `update` exits 1, naming the - required and the current version, with nothing written — `--yes` and `--force` do not skip it. -2. Takes the project lock (`pharn/.lock`) — before it reads anything or touches the network — and - holds it to the end of the run, across the confirm. While it waits for your answer, a second - `pharn` command in this project is refused, naming this one (see +1. **Node and lock.** On a Node older than **24.2.0** (the floor PHARN's installed checkers need), or one + whose version cannot be read, `update` exits 1 with nothing written; `--yes` and `--force` do not skip + it. Then it takes the project lock (`pharn/.lock`) before it reads anything or touches the network, and + holds it to its last write, so a second writing `pharn` command is refused rather than queued (see [Another pharn process is running](../troubleshooting.md#another-pharn-process-is-running)). - `--dry-run` takes no lock. Then reads `pharn.config.json`. If none exists — or it is a pre-archetype (module) config, or one - recorded at the removed `flat` layout (see [Layout migrations](#layout-migrations)) — it exits with - a hint to run `pharn init`. A config that is present but **invalid** gets its own named error - and exit 1, not the "run `pharn init`" hint. -3. Warns if a proxy is configured — emitted once at the top of the run, so it precedes **both** of - update's fetches (the lightweight version check as well as the tarball). -4. Resolves what to update to — the newest **verified release** for an install that follows releases, - or the tip of `pharn-dev/pharn-oss` `main` for one that records no `ref` (see - [Release channel](#release-channel)) — and - compares its version to your recorded `skillsVersion`. A release that cannot be resolved stops the run - (exit 1). An install **ahead** of that source — newer than the newest release, or newer than `main` - when `main` has moved back to an older version — is left as it is (exit 0) unless you pass `--force` - (see [An install ahead of its source](#an-install-ahead-of-its-source)). -5. Downloads the repo (SHA-pinned) and plans the update — **every run does, at the same skills version - too**: there is no "same version, nothing to do" shortcut, so one plain `pharn update` restores a - missing file, adds a missing `.gitignore` or `.prettierignore` line, restores a deleted `models` block, - records a `--ref` switch and re-checks a capability it kept unread. The plan checks `MIN_CLI`, - **re-resolves your recorded `archetypes`** against the latest capability index and **unions** that - result with the capabilities you added by hand. A failed download, a `MIN_CLI` refusal, or a dropped - capability whose directory cannot be deleted safely stops the run here (exit 1), before you are - asked anything. -6. If the plan **changes nothing** — no file to write, no directory or root doc to delete, no line to add - to `.gitignore` / `.prettierignore`, and `pharn.records.json` and `pharn.config.json` would stay as - they are — the install is up to date: it prints its notes (a kept edit is still listed under - `SKIPPED`), asks nothing, writes nothing, exits 0, and ends with `Up to date.` (or `Nothing to change.` - when it keeps an edit of yours; see [When there is nothing to change](#when-there-is-nothing-to-change)). -7. Otherwise shows the version bump (or `(re-applying)` at the same version) with a pointer to - `CHANGELOG.md`, lists, in a `CAPABILITIES` note, every capability the update would **add** or - **drop**, with the directory each drop would delete, and under `--force` every file it would - overwrite (see [Before you confirm](#before-you-confirm)), and asks for - confirmation — unless you passed `--yes`, which skips that one prompt and nothing else. -8. On confirm, applies the plan you were shown — it plans once. A file you edit while `update` waits for - your answer stops the run before anything is written (exit 1, with or without `--force`): the - error names the file, your edit is kept, and re-running `pharn update` plans it as yours and skips - it (see [Edits made while update waits for your answer](#edits-made-while-update-waits-for-your-answer)). - So does a hand-edit of `pharn.config.json`. Otherwise it writes what the plan decided for each - expected file with the table below — and your `models` block the same way — backs up - anything `--force` is about to overwrite and every file in a dropped capability's directory that - `pharn` cannot prove it wrote (read again at the delete, so a file you add there meanwhile is saved - too), **deletes the directories of the capabilities it drops** (see - [Dropped capabilities are deleted](#dropped-capabilities-are-deleted)), copies the files it may - write, then updates `pharn.records.json` and `pharn.config.json` — recording this CLI in - `pharnVersion` and the time of the update in `updatedAt`, and keeping `installedAt`, the date of - the first install. - -Because `update` re-resolves your archetypes against the latest index, a capability upstream added for -one of your archetypes since your last install is picked up, and one it removed is dropped — and its -directory deleted — while your `archetypes` list itself is never changed. + `pharn list`, `pharn status` and `--dry-run` never take the lock. +2. **Config.** Reads `pharn.config.json`. If none exists, or it is a pre-archetype (module) config, or + one recorded at the removed `flat` layout ([details](../reference/update-advanced.md#an-install-recorded-at-the-flat-layout)), + it exits 1 with a hint to run `pharn init`. A config that is present but **invalid** gets its own + named error and exit 1, not that hint. A configured proxy is reported once here, before either fetch. +3. **Source.** Resolves the newest **verified release**, or the tip of `main` for an install that records + no `ref` ([Release channel](#release-channel)). An unresolvable release stops the run (exit 1). An + install [ahead of that source](#an-install-ahead-of-its-source) is left as it is (exit 0) unless you + pass `--force`. +4. **Download and plan.** Downloads the repo (SHA-pinned) and plans, at the same skills version too, so + a plain `pharn update` also restores a missing file or `models` block, adds a missing ignore line, + records a `--ref` switch and re-checks a capability it kept unread. The plan checks + [`MIN_CLI`](../troubleshooting.md#pharn-is-too-old-for-the-current-pharn-oss), **re-resolves your + `archetypes`** against the latest capability index and **unions** the result with the capabilities you + added by hand. A failed download, a `MIN_CLI` refusal, or a dropped capability whose directory cannot be + deleted safely stops the run here (exit 1), before you are asked anything. +5. **Confirm.** If the plan [changes nothing](#when-there-is-nothing-to-change), it asks nothing, writes + nothing and exits 0. Otherwise it shows the version bump (or `(re-applying)`) with a pointer to + `CHANGELOG.md`, what it adds, drops and (under `--force`) overwrites ([Before you confirm](#before-you-confirm)), + and asks. `--yes` skips that one prompt and nothing else. +6. **Apply.** On confirm it applies the plan you were shown: it plans once. A file (or + `pharn.config.json`) you edit while it waits stops the run before anything is written (see + [Edits made while update waits for your answer](#edits-made-while-update-waits-for-your-answer)). + Otherwise, in order: the [backup](#--force-and-pharnbackup), the deletes of + [dropped capabilities](#dropped-capabilities-are-deleted), each write the [decision table](#the-decision-table) + allows, `pharn.records.json`, `pharn.config.json` (`pharnVersion`, `updatedAt`; `installedAt` kept), and + the `.gitignore` and `.prettierignore` lines. ### Edits made while update waits for your answer -`update` holds the project lock from before its plan to its last write, so no other `pharn` command -changes the project while the confirm is open. You, an editor or an agent still can. Before the first -write, `update` compares every file it is about to write with what it saw when it planned: +Before its first write, `update` compares every file it is about to write with what it saw when it +planned. A file whose bytes changed (or that appeared) stops the run, exit 1 even with `--force`: -- a file whose bytes changed (or that appeared) stops the run, with nothing written: - - ```text - ■ A file changed while `pharn update` was waiting for your answer: - pharn/CONSTITUTION.md - Nothing was written, and your edit is kept. Run `pharn update` again: it plans the file as - changed by you and leaves it alone (or, with --force, backs it up first). - ``` - -- a file you put back with exactly upstream's bytes is not an edit, and the run goes on; -- a hand-edit of `pharn.config.json` stops the run the same way. +```text +■ A file changed while `pharn update` was waiting for your answer: + pharn/CONSTITUTION.md + Nothing was written, and your edit is kept. Run `pharn update` again: it plans the file as + changed by you and leaves it alone (or, with --force, backs it up first). +``` -The run stops instead of skipping the file because the rest of the plan — the version it records, the -[executable unit](#the-executable-unit-is-upgraded-all-or-none) — was decided -from the bytes you have since changed. The re-run decides them again. +A file put back with exactly upstream's bytes is not an edit; a hand-edit of `pharn.config.json` stops the +run too. It stops rather than skips because the rest of the plan (the recorded version, the +[executable unit](../reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none)) rests on +the bytes you changed; the re-run decides again. ## Previewing an update @@ -115,47 +83,30 @@ pharn update --dry-run --force # ...and what would --force overwrite and back u pharn update --dry-run --ref latest ``` -`--dry-run` runs the same checks and the same per-file decisions as a real update, prints the result, -and exits **0** having **written nothing**: no file in your project, no `pharn.records.json` or -`pharn.config.json` change, no `pharn/.lock`, no `pharn/.backup/`. It needs no terminal and never -asks to confirm (`--yes` is accepted and does nothing). Use it to look before you apply — in a -terminal, or from a script or an agent that wants to read the plan first. - -What it still does, exactly like a real run: the Node check, the config load, resolving the source -(`--ref`), the "ahead of the release" and "ahead of main" early returns (reported, exit 0, nothing -downloaded), the clone — which a dry run at the current version downloads too — and the `MIN_CLI` gate -(a refusal exits 1). What it skips: the confirm, the project lock and -the check that the config did not change under you. - -It prints: - -- `PLAN` — the files it would **write** (`restored`, `updated`), under `--force` the ones it would - **overwrite** (`modified`, `unrecorded`, `unverifiable`), the capability directories it would - **delete** (`WOULD DELETE`), the files it would **back up** first - (`pharn/.backup//` — the timestamp is only known when a real run makes the backup), how - many are unchanged or skipped, and the channel it would record when `--ref` changes it; -- `Nothing would be written.` when a real run would [change nothing](#when-there-is-nothing-to-change) - (it would then ask nothing either), or `Would rewrite only pharn.config.json` (or - `pharn.records.json`, or both) when those are all it would change; under `--force` the - `WOULD OVERWRITE (--force)` groups also name `pharn.config.json` when your `models` block would be - replaced; -- the `SKIPPED`, `CAPABILITIES`, `MODELS`, `HOOKS` and `NOT SHIPPED` notes of a real run, worded as - what _would_ happen; -- whether the recorded `skillsVersion` would be **withheld** (and recorded as pending), and the layout - and features-README moves it would make. - -It is a **snapshot**, not a promise. A real run fetches again and plans again under its own lock, -so an edit you make, another process, or a newer upstream merge between the preview and the apply can -change the outcome. The only thing a dry run creates is the clone's temporary directory under your OS -temp directory, removed before it exits. +`--dry-run` runs the same checks, download and per-file decisions as a real update (a `MIN_CLI` refusal +still exits 1), prints the result, and exits **0** having **written nothing**: no project file, no state +file, no `pharn/.lock`, no `pharn/.backup/`. It needs no terminal, never asks, and skips the lock and the +check that the config did not change under you. It prints: + +- `PLAN`: the files it would **write** (`restored`, `updated`), under `--force` the ones it would + **overwrite** (`modified`, `unrecorded`, `unverifiable`, and `pharn.config.json` when your `models` + block would be replaced), the capability directories it would **delete** (`WOULD DELETE`), the files + it would **back up** first (the `` is known only when a real run makes it), the counts of unchanged and skipped files, and the channel it would + record when `--ref` changes it; +- `Nothing would be written.` when a real run would change nothing, or `Would rewrite only +pharn.config.json` (or `pharn.records.json`, or both) when those are all it would change; +- the `SKIPPED`, `CAPABILITIES`, `MODELS`, `HOOKS`, `ORPHANED` and `NOT SHIPPED` notes, worded as what + _would_ happen, and whether the recorded `skillsVersion` would be **withheld** (and recorded as + pending). + +It is a **snapshot**, not a promise: a real run fetches and plans again under its own lock. The only +thing a dry run creates is the download's directory under your OS temp directory, removed before it exits. ### JSON output -`pharn update --dry-run --json` (also `pharn update --json`) prints the same plan as **one JSON object** -on stdout and nothing else, and exits 0 whatever it contains; the outcome is its `status` (`planned`, -`up-to-date`, `ahead-of-release`, `ahead-of-main`), and `--compact` leaves out the unchanged files. Its -keys, the `schemaVersion` 1 stability rule and a real example are in the -[JSON output reference](../reference/json-output.md#update). +`pharn update --json` prints the same plan as **one JSON object** on stdout and nothing else, and exits 0; +the outcome is its `status` (`planned`, `up-to-date`, `ahead-of-release`, `ahead-of-main`), and `--compact` +leaves out the unchanged files. Keys and an example: [JSON output reference](../reference/json-output.md#update). ## What happens to your capability list @@ -166,121 +117,51 @@ next capabilities = resolve(your archetypes, latest index) ← the `source: "a ∪ every `source: "manual"` entry still in the latest index ``` -So a capability you installed with [`pharn add`](add.md) **survives an update that does not select it**, -as long as it still exists upstream — a manual entry whose capability has been removed from the index is -dropped instead (named under `REMOVED — no longer exists upstream`). Its files are upgraded, restored, or -skipped-on-edit by the same table below as everything else when it is kept. An entry that is both manual -and re-selected stays `manual`, so a later archetype change cannot quietly drop it. A capability you -removed with [`pharn remove`](remove.md) returns only when the latest resolution still selects it for your -archetypes — then it re-enters as `auto` and is named under `ADDED`. See -[`capabilities[].source`](../reference/pharn-config.md#capabilitiessource--selection-provenance). +A capability you added with [`pharn add`](add.md) **survives an update that does not select it** while it +still exists upstream; an entry both manual and re-selected stays `manual`. One you removed with +[`pharn remove`](remove.md) returns, as `auto` under `ADDED`, when your archetypes still select it: a removal +is not a tombstone. See [`capabilities[].source`](../reference/pharn-config.md#capabilitiessource--selection-provenance). -**Every membership change is named.** When the list changes, `update` prints a `CAPABILITIES` section: +**Every membership change is named** in a `CAPABILITIES` note (nothing is printed when nothing changed): -| Reported as | Meaning | -| --------------------------------------------------------- | --------------------------------------------------------------- | -| `ADDED — newly selected for your archetypes` | New upstream for your archetypes, or re-selected after a remove | -| `REMOVED — no longer selected for your archetypes` | An `auto` entry your archetypes no longer select | -| `REMOVED — no longer exists upstream (was a manual add)` | A `manual` entry whose capability is gone from the index | -| `KEPT — your manual add, not selected by your archetypes` | A pre-`source` entry preserved as manual (printed once) | -| `KEPT — pharn could not read these upstream this run` | A capability this pharn version could not parse (see below) | +| Reported as | Meaning | +| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `ADDED — newly selected for your archetypes` | New upstream for your archetypes, or re-selected after a remove | +| `REMOVED — no longer selected for your archetypes` | An `auto` entry your archetypes no longer select | +| `REMOVED — no longer exists upstream (was a manual add)` | A `manual` entry whose capability is gone from the index | +| `KEPT — your manual add, not selected by your archetypes` | A pre-`source` entry preserved as manual (printed once) | +| `KEPT — pharn could not read these upstream this run` | [A capability this pharn version could not parse](../reference/update-advanced.md#when-pharn-cannot-read-a-capability-upstream) | -If nothing changed, nothing is printed. A `REMOVED` line also says what happened to that capability's -directory: `directory deleted`, `directory deleted (N file(s) backed up first)`, or `already gone`. +A `REMOVED` line also says `directory deleted`, `directory deleted (N file(s) backed up first)` or `already gone`. ### Dropped capabilities are deleted -PHARN's commands find the grillers and lenses they run by **scanning their directories** — not by -reading `pharn.config.json`. So a capability `update` drops from the config (either `REMOVED` reason -above) would keep running if its directory stayed, and `pharn remove` could no longer reach it, since -`remove` addresses what the config lists. `update` therefore **deletes that directory** in the same run, -inside the project lock, the way [`pharn remove`](remove.md) does: - -- **Backed up first.** Every regular file in the directory that is not, provably, `pharn`'s own - unchanged bytes is copied to `pharn/.backup//` before the first delete: a file you added, - a file you edited, and **every** file when there is no usable `pharn.records.json`. A file still at the - hash `pharn` recorded writing is not copied; `pharn add` can install it again. The backup is named when - it is created (`Backed up N file(s) to pharn/.backup/ before removing.`), and it is the same one - directory `--force` uses in that run (`before overwriting and removing.`). Symbolic links, FIFOs and - sockets inside the directory are not backed up and not followed; the delete removes a link, never its - target. -- **Addressed where it was installed.** The directory is found at the layout `pharn.config.json` - recorded, by the capability's validated name, and only ever as a direct child of its role's - directory (`pharn-pipeline/grillers/` or `pharn-review/`, under `pharn/` in that layout). -- **Refused, with nothing changed,** when the path to it crosses a symbolic link (deleting through it - would delete files outside the project — delete the directory yourself, then run `update` again), or - when a file in it cannot be read (an unreadable file is never assumed to be `pharn`'s). Exit 1. -- **Before the writes.** The order is backup → delete → copy → `pharn.records.json` → - `pharn.config.json`. If the backup fails, nothing is deleted. If a delete fails, nothing has been - written yet; the config still lists the capability, so the next `update` drops it again. -- **Upstream decides membership.** Which capabilities your archetypes select, and which still exist, - comes from the fetched `pharn-oss` index — so a capability upstream stops listing for you has its - directory deleted on your next `update`. That is bounded: only the one directory of a capability your - `pharn.config.json` lists, addressed by its validated name, with your files backed up first. Preview it - with `pharn update --dry-run`. -- **Visible beforehand.** The confirm names each dropped capability and the directory it deletes (see - [Before you confirm](#before-you-confirm)), and defaults to **No** when anything is deleted. - `pharn update --dry-run` lists the same directories under `WOULD DELETE` (and - `plan.capabilities.removals` under `--json`) without asking. - -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 -drops the same way, after listing them in its overwrite prompt. - -> **Named limit — removals are not permanent.** `pharn remove` drops the entry from `capabilities`; -> it does not record a tombstone. If your archetypes still select that capability, the next `update` -> re-adds it — but it will now **say so** under `ADDED`, instead of resurrecting it in silence. -> `pharn remove` warns you about this at removal time for an `auto` capability. - -## When pharn cannot read a capability upstream - -`update` fetches the source your install follows — the newest verified release of `pharn-dev/pharn-oss` -(the default), or the tip of `main` for an install on `--ref main` — so a capability can change upstream in a way -your installed pharn version does not understand yet — a new field value, a directory that does not -have its markdown yet, a shape from a newer release. When that happens `update` **skips that one -capability and says so**; it does not abort: - -```text -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. -``` - -What `update` does with it: - -- **Nothing under that capability's directory is written into your project.** pharn will not copy - content it could not validate. -- **Your `pharn.config.json` entry is kept**, reported as `KEPT — pharn could not read these -upstream this run`. A capability you have is not dropped because one fetch could not read it. -- **Everything else updates normally**, including the skills version — so the next - [`pharn add`](add.md) is 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 pharn with `npm install -g @pharn-dev/pharn@latest`), `update` -brings its files up to date as usual and clears the field — but only once none of that capability's -files had to be skipped. A file of it you edited is skipped as usual, and the capability stays listed, -so every later run checks it again until you resolve the edit or pass `--force`. If you no longer want -the capability at all, remove it with [`pharn remove`](remove.md). - -## `pharn is too old for the current pharn-oss` - -pharn-oss can ship a root `MIN_CLI` file declaring the **minimum pharn version** its content needs. -When your installed version is older, `init` / `add` / `update` refuse **before writing anything**, -clean up the temporary clone, and exit 1: - -```text -⚠ This pharn is too old for the current github.com/pharn-dev/pharn-oss: it requires - @pharn-dev/pharn v0.9.0 or newer, and v0.4.0 is installed. Upgrade …, then re-run - this command. Nothing was written. -``` - -Upgrading is the fix. A `MIN_CLI` file that is missing, unreadable, or malformed imposes **no** -constraint (a warning at most) — only a well-formed version newer than yours ever refuses. +PHARN runs the grillers and lenses it finds **on disk**, not those `pharn.config.json` lists, so a dropped +capability would keep running if its directory stayed. `update` **deletes that directory** in the same run, +the way [`pharn remove`](remove.md) does: + +- **Backed up first.** Every regular file in it that is not provably `pharn`'s own unchanged bytes (a file + you added or edited, and **every** file when there is no usable `pharn.records.json`) is copied to + `pharn/.backup//` before the first delete, announced as + `Backed up N file(s) to pharn/.backup/ before removing.` (`before overwriting and removing.` when + `--force` shares the directory). A file still at the hash `pharn` recorded is not copied: `pharn add` can + install it again. The set is read again at the delete, so a file you add meanwhile is saved too. Symbolic links, + FIFOs and sockets inside are not backed up and not followed; the delete removes a link, never its target. +- **Addressed where it was installed**: by the capability's validated name, only ever as a direct child of + `pharn/pharn-pipeline/grillers/` or `pharn/pharn-review/`. +- **Refused, with nothing changed** (exit 1), when the path crosses a symbolic link (delete the directory + yourself, then re-run) or a file in it cannot be read (an unreadable file is never assumed to be `pharn`'s). +- **Before the writes.** A failed backup deletes nothing; a failed delete has written nothing yet, and the + config still lists the capability, so the next `update` drops it again. + +Upstream's index decides membership, so a capability upstream stops listing for you is deleted on your +next `update` (preview it with `--dry-run`, `WOULD DELETE`). Apart from its lock and download, that +directory is all `update` deletes: never a file upstream stops shipping +inside a capability it keeps ([orphans](../reference/update-advanced.md#orphaned-files)), and never +`.claude/settings.json`. Every delete `pharn` makes is listed in [What PHARN deletes](../reference/deletes.md). +A directory an older `pharn` left behind when it dropped only the config entry has no entry, so `update` +cannot find it (`pharn list` does not show it, but PHARN still runs it): delete it by hand. A re-run +[`pharn init`](init.md#dropped-capabilities-are-deleted) deletes dropped directories the same way. ## The decision table @@ -295,299 +176,91 @@ Evaluated per file, first match wins: | 5 | present | available | no record for this path | **skip** `unrecorded` | back up → write | | 6 | present | unavailable | — | **skip** `unverifiable` | back up → write | -"Identical" in rows 2–4 compares content with line endings ignored in text files: a file that differs -only by CRLF vs LF line endings (for example after a `core.autocrlf=true` checkout) counts as identical, -and a line-ending-only edit is not seen as `modified`. See -[Line endings](../troubleshooting.md#line-endings-windows-coreautocrlf). - -A file that is already identical to upstream (row 2) is never a skip, even with no records — and -its record is refreshed, so a degraded install partially heals itself. Partially: it never recovers -records for the files that **differ**, which is exactly the set an upgrade needs to touch. Those stay -skipped until you `--force` them or restore them yourself. - -There is a seventh outcome the table cannot cause: a path that is **not a readable regular file** (a -directory where a file belongs, an unreadable file, a symlink — at the path itself or at any parent -directory below your project root) is reported as `unreadable` and skipped — including under -`--force`. It need not exist for that: a dangling parent symlink, or a parent that is a regular file, -also lands here rather than in the restore row, because something is in the way. When a symlink is the -cause the reason **names the offending component**, so a `.claude/hooks` symlinked into a dotfiles repo -is named as that directory; the other cases give a generic reason. - -**Each file is written by replacement.** `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. - -### The skip labels - -- **`modified`** — you changed this file after `pharn` wrote it. This is the label the feature exists - for. -- **`unrecorded`** — `pharn` has no record of writing this path. Usually a file of your own that - collides with a path upstream newly added, or a file installed before records existed. -- **`unverifiable`** — there is no usable `pharn.records.json` at all, so nothing can be proven about - any file. Every install created before `pharn` 0.4.0 starts here (see - [First update after upgrading](#first-update-after-upgrading)). -- **`held`** — not a reason of its own: the file would have been written, but it belongs to the - [executable unit](#the-executable-unit-is-upgraded-all-or-none) and another file of the unit was - skipped. - -Skips **exit 0**. A skip is the outcome you asked for, not a failure. `pharn update` also never -**deletes a file** it decides about here: a file upstream no longer ships stays exactly where it is — and is listed, see -[Orphaned files](#orphaned-files). The one thing it deletes is the directory of a capability it drops from -the config — see [Dropped capabilities are deleted](#dropped-capabilities-are-deleted). - -## The executable unit is upgraded all or none - -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 to decide -whether it belongs. 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: - -```text -◇ 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 `skillsVersion` is **withheld**, as for any skip. -- When every file that blocked the unit (and every other skipped file) is one **you edited** - (`modified` or `unrecorded`), the version the run applied is recorded as `pendingSkillsVersion`, as - for any skip caused only by your edits. [`pharn add`](add.md) then installs at that version: it writes - capability directories only, which are outside the unit and were upgraded anyway. When any blocker is - something else (`unverifiable` because there is no usable record store, or `unreadable`), nothing is - recorded, and `pharn add` refuses until the update can finish. `pharn update --dry-run` shows 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: `pharn` never 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 (revert your edit, or run - `pharn update --force`). [`pharn status`](status.md) reports 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: nothing you edited was overwritten and nothing failed. The note is - the signal, not the exit code. -- `--force` never holds. It backs up the skipped files and writes the whole set (an `unreadable` path is - still skipped, as always). -- 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](#json-output)). - -## 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 (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 update` never - deletes them, and keeps listing each one until it is gone. +"Identical" ignores line endings in text files: a file that differs only by CRLF vs LF counts as identical, +and a line-ending-only edit is not `modified` (see +[Line endings](../troubleshooting.md#line-endings-windows-coreautocrlf)). A file already identical to +upstream (row 2) is never a skip and its record is refreshed, so a degraded install partially heals; the +files that **differ** stay skipped until you `--force` them or restore them yourself. - UNCHANGED — unchanged since pharn wrote it - .claude/commands/pharn-old.md +A seventh outcome is outside the table: a path that is **not a readable regular file** (a directory, an +unreadable file, a symlink at the path or at any parent below your project root; it need not exist, so a +dangling parent symlink or a parent that is a file lands here too) is `unreadable` and skipped, under +`--force` too. A symlink cause names the component (a `.claude/hooks` linked into a dotfiles repo is named as +that directory); other causes give a generic reason. Each write +[replaces the file](../reference/update-advanced.md#writes-replace-the-file). - EDITED — changed since pharn wrote it — review before deleting - .dev/floor/check-old.mjs +### The skip labels - Delete the ones you no longer need by hand (e.g. `git rm `). -``` +- **`modified`**: you changed this file after `pharn` wrote it. This is the label the feature exists for. +- **`unrecorded`**: `pharn` has no record of writing this path, usually a file of your own that collides + with a path upstream newly added. +- **`unverifiable`**: there is no usable `pharn.records.json` at all, so nothing can be proven about any + file (see [No usable records store](../reference/update-advanced.md#no-usable-records-store)). +- **`held`**: not a reason of its own: the file would have been written, but it belongs to the + [executable unit](../reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none) and + another file of the unit was skipped. -- **`UNCHANGED`**: the file still has the exact bytes `pharn` recorded 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. `pharn` does 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`. - -**It stays listed until you delete it.** `update` keeps the orphan's entry in `pharn.records.json` (its -old hash, unchanged) for as long as the file exists, so every later `update` — and every -[`pharn status`](status.md#orphaned-files) — still names it. Once the file is gone, the next `update` -drops its entry, at the same skills version too: it restores nothing (upstream no longer ships the -file), drops the entry, 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 `pharn` has no record of — an install made before records existed, or files written while - `pharn.records.json` was unusable. 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 `CAPABILITIES` note, and its directory is deleted (see - [Dropped capabilities are deleted](#dropped-capabilities-are-deleted)). -- Anything outside the paths an install can write (`.claude/commands/pharn-*.md`, `.claude/hooks/*.cjs` or `*.mjs`, - the capability directories, `pharn-contracts/`, `pharn-core/`, the floor directory, the trusted docs, - the PHARN license and the features `README.md`, in either layout) — even if a hand-edited - `pharn.records.json` names it. - -Every run plans, so an up-to-date run prints the `ORPHANED` note too; -[`pharn status`](status.md#orphaned-files) reports orphans whenever it runs its drift check. -`--dry-run` prints the same note, and `--dry-run --json` lists them 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. +Skips **exit 0**: a skip is the outcome you asked for, not a failure. `pharn update` never deletes a file it +decides about here; a file upstream no longer ships stays and is listed under `ORPHANED` (see +[Orphaned files](../reference/update-advanced.md#orphaned-files)). ## `--force` and `pharn/.backup/` -`--force` overwrites all three skip buckets — but every affected file is first copied, with its -relative path preserved, into: +`--force` overwrites the `modified`, `unrecorded` and `unverifiable` buckets (never `unreadable`), but every +affected file is first copied, with its relative path preserved, into: ```text pharn/.backup// ``` -The directory is printed when it is created — on **both** paths. If the update then fails part-way -(a directory it cannot delete, a file it cannot write, a config it cannot save), it still names the -directory before exiting 1, alongside a line telling you some originals may already have been -overwritten (or removed). The same directory holds the files saved from -[dropped capabilities](#dropped-capabilities-are-deleted), with or without `--force`. That path is your only -route back to your pre-overwrite bytes, so it is never withheld at the moment you need it most, and -earlier runs may have left other timestamped directories beside it. - -If **any** backup copy fails, nothing is printed and nothing is at risk: the update aborts before a -single original is touched. A colliding timestamp directory is never written into — the run -uniquifies (`…-2`, `…-3`) instead, so a second `--force` in the same second cannot overwrite the only -surviving copy of your edits. - -To restore a file, copy it back: +The directory is printed when it is created, and again, with a warning that some originals may already be +overwritten or removed, if the update then fails part-way (a directory it cannot delete, a file it cannot +write, a config it cannot save; exit 1). Earlier runs may have left other timestamped directories beside it. It also holds the files saved from +[dropped capabilities](#dropped-capabilities-are-deleted). If **any** backup copy fails, the update aborts +before a single original is touched; a colliding timestamp gets `…-2`, `…-3`. To restore a file: ```bash cp pharn/.backup/20260807-091500/pharn/CONSTITUTION.md pharn/CONSTITUTION.md ``` -**Retention is yours.** `pharn` never prunes `pharn/.backup/`, so backups accumulate. They are kept out -of git by the `pharn/.backup/` line `update` (and `init`) append to your `.gitignore` — see -[`.gitignore`](#gitignore). Delete them once you are happy. +**Retention is yours.** `pharn` never prunes `pharn/.backup/`; the `pharn/.backup/` line `init` and `update` +add to your [`.gitignore`](../reference/update-advanced.md#gitignore) keeps it out of git. ## Release channel -`update` follows the channel your install records. An install that follows **releases** (`"ref": -"latest"` — what `pharn init` writes by default) gets the newest **GitHub release** — a tag pharn-oss -creates only once every required check on that commit has passed after the merge — at exactly the -commit the tag points at, never a commit whose CI is unfinished, cancelled or red. An install with no -`ref` (made with `--ref main`, or before `--ref` existed) gets the tip of `pharn-dev/pharn-oss` `main` — -whatever merged last. - -- **An install on `main` is never moved for you.** Verified releases are the default for _new_ installs - only. An `update` on a `main` install keeps it on `main` and prints one line saying so: - `Verified releases are now the default for new installs. This install keeps following pharn-oss main; -run`pharn update --ref latest`to switch (recorded on first use).` It prints on every such run — - an up-to-date run and `--dry-run` included — but not when you pass `--ref`, and not under - `--json` (the report's `channel` says `main`). - -- **The channel is recorded.** `pharn update --ref latest` writes `"ref": "latest"` to - `pharn.config.json`, so later `update`, `add` and `status` runs keep following releases. - `pharn update --ref main` switches back and removes the key. A switch re-applies even at the current - version, so it is recorded. +An install that follows **releases** (`"ref": "latest"`, `pharn init`'s default) gets the newest pharn-oss +**GitHub release** (a tag created once every required check on its commit passed), at that commit. An +install with no `ref` (made with `--ref main`) gets the tip of `main`. + +- **An install on `main` is never moved for you.** Each `update` on it (`--dry-run` too; not with `--ref` + or `--json`) prints ``Verified releases are now the default for new installs. This install keeps following pharn-oss main; run `pharn update --ref latest` to switch (recorded on first use).`` +- **The channel is recorded.** `pharn update --ref latest` writes `"ref": "latest"`, so later `update`, `add` + and `status` runs follow releases; `pharn update --ref main` removes the key. A switch re-applies even at + the current version, so it is recorded. - **No fallback.** When the release cannot be resolved (none published, `api.github.com` unreachable or - rate-limited), `update` exits 1 before cloning and names `--ref main`. See + rate-limited), `update` exits 1 before downloading and names `--ref main`. See [No verified release could be resolved](../troubleshooting.md#no-verified-release-could-be-resolved). -- **Ahead of the release.** An install made from `main` can be newer than the newest release. Applying - the release would be a downgrade, so `update --ref latest` says so and exits 0 without changing - anything. `--ref main` switches back to `main`; `--force` goes back to the release (backing up your - edits as usual). See [An install ahead of its source](#an-install-ahead-of-its-source). ### An install ahead of its source -`update` never moves your install to an **older** version without being asked. On either channel, when -the version you have is newer than the one the source offers, it reports that, changes nothing, and -exits 0: +`update` never moves your install to an **older** version without being asked. When the version you have +is newer than the source offers, it says so, changes nothing, and exits 0: -- **On `--ref latest`** — the install came from `main` and the release at its version is not cut yet - (above). -- **On `main`** — pharn-oss `main` has **moved back**: a revert took its `SKILLS_VERSION` below the one - you installed from it. Without this check, `update` would have shown `v2.0.0 → v1.0.0` and applied the - older files over every clean one. It now prints +- **On `--ref latest`**: the install came from `main` and no release at its version exists yet; + `--ref main` switches back to `main`. +- **On `main`**: `main` has **moved back** (a revert took its `SKILLS_VERSION` below yours): `Your install (skills v2.0.0) is newer than pharn-oss main (v1.0.0) — main has moved back to an older version. Nothing changed.` - Wait for `main` to move forward again, or pass `--force` to downgrade (your edits are backed up first, - as usual). - -A `pendingSkillsVersion` counts too: when the last run withheld the version bump only because of your kept -edits, every file outside those edits (and outside an executable unit they held back) is already at that -version, so an upstream older than it is refused the same way -even if your recorded `skillsVersion` is older still. The check runs before the download and the plan -— so nothing a plan would do (re-check a kept unreadable capability, restore a deleted `models` block, -record a `--ref` switch) happens, and `update --ref main` on a release install that is ahead of `main` -changes nothing, the switch included. `--dry-run` reports the same outcome, and `--dry-run --json` reports it as `status` -`ahead-of-release` or `ahead-of-main` with `plan: null`. `--yes` does not skip it; only `--force` does. -`pharn status` reports such an install as **ahead**, not outdated, and `--strict` does not fail on it. -A version that cannot be ordered (not a plain `X.Y.Z`) is never treated as ahead. - -## The `models` block - -`models` in `pharn.config.json` is **pharn-oss's** block: the source of truth each `/pharn-*` -command's `model:` / `effort:` frontmatter is held to, and which `/pharn-ship` and `/pharn-loop` read to -pick the model they request for the stages they route (see -[pharn.config.json](../reference/pharn-config.md#models)). `update` decides it with the table above, -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, never replaced. -The block's record lives in [`pharn.records.json`](../reference/pharn-records.md#the-models-block). - -**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` that neither Claude -Code nor pharn-oss's checker accepts) — stays exactly as it is, and the `MODELS` note lists what the -rules reject in it. To replace it, either edit the block by hand, or delete the `models` key from -`pharn.config.json` so the next `pharn update` writes pharn-oss's (the "absent" row above). `--force` -replaces it too, after backing up `pharn.config.json`, but it 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` no longer converts the old format (0.19.x was the last release that did). - -A kept block never holds back the skills version, unlike a skipped file: your `models` block is -configuration, and a block you tuned is a steady state, not an unfinished upgrade. Keep in mind what -the block is for, though — 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, until you restore it or use `--force`. -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. + Wait for `main` to move forward. + +A `pendingSkillsVersion` counts too. The check runs before the download, so nothing else happens, a +`--ref` switch included (`--json`: `status` `ahead-of-release` / `ahead-of-main`, `plan: null`). `--yes` +does not skip it; `--force` downgrades, backing up your edits. `pharn status` calls such an install +**ahead**, not outdated. A version that is not a plain `X.Y.Z` is never ahead. ## Non-interactive use (CI, scripts, pipes) -`update` confirms before it writes, so it needs either a terminal or your explicit consent. Off a TTY — -in CI, a pipe, or any script — it **exits 1** with a usage error rather than rendering a prompt nobody -can answer: +`update` confirms before it writes. Off a TTY, without `--yes`, it **exits 1** before any network call, +writing nothing: ```console $ echo "" | pharn update @@ -597,35 +270,16 @@ $ echo $? 1 ``` -The refusal happens **before any network call** — no version check, no clone — and writes nothing. - -Pass `--yes` (`-y`) to give that consent up front: - -```bash -pharn update --yes # the usual CI line -pharn update --yes --force # the full re-apply: overwrite local edits too -``` - -`--yes` skips **the confirmation prompt and nothing else**. Everything else is byte-identical to an -interactive run: the version note still prints, the same per-file decision table applies, files you -edited are still skipped (not overwritten), the recorded version is still withheld when anything was -skipped, and the exit codes are unchanged. It means "do not ask" — not "non-interactive mode" — so it -works in a terminal too. - -Because `--yes` is only consent, it is **not** a drift check: a run that skips your edited files still -exits 0. Use [`pharn status --strict`](status.md) when you want CI to fail on drift. - -`--force` does **not** imply `--yes`. Overwriting your edits is the most destructive thing `update` -does, so it still asks — `pharn update --force` in a pipe is refused exactly like a bare one. - -> [`pharn init --yes`](init.md#install-without-prompts---yes) skips init's "Ready to install?" question -> but never confirms an overwrite: it installs only into a project where none of its files exists yet. +Pass `--yes` (`-y`; `--yes --force` for the full re-apply). It skips **the confirmation prompt and nothing +else**: the version note and the other notes still print, edits are still skipped, the version still withheld, the exit codes unchanged. It is **not** a drift +check (a run that skips your edits exits 0): use [`pharn status --strict`](status.md) for that. `--force` +does **not** imply `--yes`. ([`pharn init --yes`](init.md#install-without-prompts---yes) never confirms an +overwrite.) ## Before you confirm -`update` downloads and plans **before** it asks, so the question can say what the run changes. When the -update adds or drops capabilities, a `CAPABILITIES` note lists them first, in the same words the -[dry run](#previewing-an-update) uses: +`update` downloads and plans **before** it asks, so the question says what the run changes. When it adds +or drops capabilities, a `CAPABILITIES` note lists them first, in the dry run's words: ```text ◇ CAPABILITIES @@ -639,9 +293,8 @@ update adds or drops capabilities, a `CAPABILITIES` note lists them first, in th │ Files in them pharn did not write would be copied to pharn/.backup/ first. ``` -With `--force`, an `OVERWRITE` note then lists every file the run will overwrite, grouped by why each -needed `--force` — the same groups as the dry run's `WOULD OVERWRITE (--force)` — and -`pharn.config.json` when your `models` block is replaced: +With `--force`, an `OVERWRITE` note then lists every file it will overwrite, grouped by why each needed +`--force`, and `pharn.config.json` when your `models` block is replaced: ```text ◇ OVERWRITE @@ -651,251 +304,46 @@ needed `--force` — the same groups as the dry run's `WOULD OVERWRITE (--force) │ Each is copied to pharn/.backup// first (1 file(s)). ``` -The question is `Apply this update?` (`Apply this update and overwrite your changes?` with `--force`). -When the update deletes a capability directory it adds how many — `It deletes 1 capability directory.` — -and the default answer becomes **No**, as `pharn init` does when it would overwrite or delete. With -nothing to delete the default stays Yes. Declining exits 0 with nothing written. `--yes` prints the same -note and skips only the question, so a CI log names what the run changed. - -The list is a snapshot. After you answer, `update` takes the project lock and plans again from the same -download (no second download) against your project as it is then: which files are skipped, backed up and -written is decided there. The capabilities it changes and the directories it deletes must match what you -were shown. If they do not — for example a dropped capability's directory reappeared while the prompt was -open — the run stops with `The capabilities this update would change are no longer what you confirmed`, -naming both sides, exit 1, nothing changed; run `pharn update` again. - -The cost of asking with that knowledge: the ~2.5 MB download happens before the question, so answering No -— or a run refused by another pharn process's lock — has already downloaded it (and removed it again). -The terminal check still comes first: off a terminal without `--yes`, `update` refuses before any network -call. +The question is `Apply this update?` (`Apply this update and overwrite your changes?` with `--force`). When +it deletes a capability directory it says how many (`It deletes 1 capability directory.`) and defaults to +**No**; with nothing to delete it defaults to Yes. Declining exits 0 with nothing written. `--yes` prints the +same notes and skips only the question, so a CI log names what the run changed. The ~2.5 MB download +happens before the question. ## When there is nothing to change -A run whose plan changes nothing does not ask and does not write. "Nothing" means all of these: no file -to write or restore, no capability directory or root doc to delete, nothing to move, no line to add to -`.gitignore` or `.prettierignore`, the same `pharn.records.json`, and the same `pharn.config.json` apart -from `updatedAt` and `pharnVersion`. Those two describe a write, not your install, so they change only on -a run that writes something — a run that changes nothing leaves `pharn.config.json` byte for byte, and -`git status` clean. - -The common case is a [kept edit](#the-recorded-version-stays-true): the version bump is withheld, so every -later run still plans, and before 0.20.0 each one asked to confirm and rewrote `pharn.config.json` with a -new `updatedAt`. Now such a run prints its notes — the `SKIPPED` note naming your edit, the withheld-version -warning — and ends with: +A run whose plan changes nothing does not ask and does not write. "Nothing" means no file to write or +restore, no capability directory to delete, no line to add to `.gitignore` or `.prettierignore`, the same +`pharn.records.json`, and the same `pharn.config.json` apart from `updatedAt` and `pharnVersion` (which +change only on a run that writes something, so `git status` stays clean). It prints its notes (a kept edit +is still listed under `SKIPPED`) and ends with: - `Nothing to change.` when something is skipped or the recorded version is behind upstream; - `Up to date.` when nothing is skipped and the recorded version is the one upstream ships. -A [held executable unit](#the-executable-unit-is-upgraded-all-or-none) counts the same way: the first held -run that records `pendingSkillsVersion` changes `pharn.config.json`, so it asks and writes even when no file -is written; the runs after it change nothing until something does: you revert the edit, run with `--force`, or upstream moves on. - -The comparison is made against `pharn.config.json` as `pharn` reads it, so a value the reader already -resolves never forces a write on its own: no `commit` key is `null`, a `ref` other than `"latest"` is -`main`. A real difference — you switch channel, a new commit — still changes the file. +A missing `commit` (`null`) or a `ref` other than `"latest"` never forces a write by itself; recording a +new `pendingSkillsVersion` does. The dry run ends `Dry run — Up to date.` (or `Nothing to change.`), and +`--json` reports `status` `up-to-date` with `plan: null`. -The terminal check is unchanged: off a terminal without `--yes`, `update` still refuses before any network -call, because it cannot know the plan until it has downloaded. The [dry run](#previewing-an-update) says -`Nothing would be written.` and ends `Dry run — Up to date.` (or `Nothing to change.`) for the same plans, -and `--dry-run --json` reports them as `status` `up-to-date` with `plan: null`. Since 0.20.0 this is the -only "up to date": every run, at the current skills version too, downloads pharn-oss (about 2.5 MB) and -plans before it can say so. - -## Concurrency +## The recorded version stays true -`update` takes the project lock (`pharn/.lock`) **before** it reads `pharn.config.json` or touches the -network, and holds it across the download, the plan, the confirm and the writes. While it waits for your -answer, a second `pharn` writer refuses with a named message and exit 1 rather than queueing; `pharn list` -and `pharn status` never take the lock, so `pharn status --strict` stays runnable in CI while an update is -in flight. A refused run reads nothing and fetches nothing. `--dry-run` takes no lock. See -[Another pharn process is running](../troubleshooting.md#another-pharn-process-is-running). +A run that skipped anything **does not** advance `skillsVersion` / `commit`: they describe the last +**complete** state, so `pharn status` keeps reporting an update, and the next `pharn update` has work to do. When every skip is an edit of yours (`modified` or `unrecorded`), the +version the run applied is recorded as `pendingSkillsVersion`, and [`pharn add`](add.md) installs at it. +Once the skips are resolved (revert, or `--force`), the version advances; a kept edit keeps the install +showing as outdated, which is the honest report. -## The recorded version stays true +## Less common situations -If a run skipped anything, it **does not** advance the `skillsVersion` / `commit` in -`pharn.config.json`. Those fields describe the last **complete** state, so: - -- `pharn status` keeps reporting that an update is available — because one genuinely is, -- and the next `pharn update` still has work to do instead of exiting early forever. +In [update: less common situations](../reference/update-advanced.md): -Once the skips are resolved (you revert the files, or re-run with `--force`), the run is complete and -the version advances. The trade-off is deliberate: a project that permanently keeps a local edit to a -PHARN-owned file will keep showing as outdated, which is the honest report. - -## First update after upgrading - -Installs created before `pharn` 0.4.0 have no `pharn.records.json`. On the first `pharn update` after -upgrading, every file that differs from upstream is skipped as `unverifiable` — `pharn` cannot tell -your edits from upstream's changes, and guessing is exactly what it refuses to do. - -Resolve it once, either way: - -- `pharn update --force` — overwrite them, keeping a backup of the current bytes; or -- inspect the listed files first (`pharn status` shows the same set), revert what you did not intend - to keep, and re-run `pharn update`. - -Either path writes a full record store, and every later update is precise. - -## Missing files at the same skills version - -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, the -[review lens agent](#the-review-lens-agent-claudeagents) an older `pharn` never installed, or a surface a -newer `pharn` release installs that your install never had. The per-file table always `restore`s a -missing file, so your edits elsewhere are still kept and no `--force` is needed. `--dry-run` shows it -under `WOULD WRITE — restored`, and `--dry-run --json` reports `status` `planned`. After that run the -install is complete again and the next `update` answers `Up to date.` - -A path that goes through a symbolic link is never followed and is not restored — `update` refuses to -write through a link — 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`](status.md) reports it. - -A capability you removed with [`pharn remove`](remove.md) is restored too when your archetypes still -select it: every run re-resolves them (see -[Removing an auto-selected capability](remove.md#removing-an-auto-selected-capability)). - -## A records store from an interrupted run - -[`pharn.records.json`](../reference/pharn-records.md) 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. Earlier releases made the stamp a gate: such a store was ignored, that release read every -differing file as `unverifiable`, and the files then lost their records and read as `unrecorded` on -every later run, until `--force`. -The two edge cases of trusting the hash alone are in -[The stamp is not a gate](../reference/pharn-records.md#the-stamp-is-not-a-gate). - -A store that is **absent** or **unreadable** (invalid JSON, an unknown `schemaVersion`) is still not -used: every present file that differs from upstream is `unverifiable` and the run names the reason. -Every file that matches upstream is recorded again, so a plain `update` at the same skills version writes -a new store over the unreadable one (copy it aside first if you want to repair it by hand). The record of -a `.claude/settings.json` that `init` created cannot be rebuilt that way: `update` never writes that file. - -## A surface added by a newer CLI, at the same skills version - -When a **new `pharn` release starts installing a surface that earlier releases did not** — as the -release adding `pharn/pharn-core/` does — an install pinned at the _current_ skills version is missing -those files. [`pharn status`](status.md) reports them as `missing`, and `pharn status --strict` exits -`1`, until a plain `pharn update` restores them: every run compares every file against upstream, at the -same skills version too (missing files are always `restore`d — there is nothing local to protect). - -### The review lens agent (`.claude/agents/`) - -pharn-oss ships `.claude/agents/pharn-review-lens.md` from skills version 6.64.0 on: the subagent -`/pharn-review` runs each lens in (without it, each lens runs as a general-purpose agent with more -tools). Earlier `pharn` releases did not install it. A plain `update` adds it, at any skills version that -ships it, with no `--force`, and records it; the next `update` answers `Up to date.`, and a later deletion -is [restored](#missing-files-at-the-same-skills-version) like any recorded file. An edited agent is kept -as `modified`, and a `.claude/agents` that is a symbolic link is never written through. - -## Layout migrations - -There are none any more. The legacy `flat` layout (PHARN's files at the project root, `"layout": "flat"` -in `pharn.config.json`, or no `layout` key) was deprecated in v0.20.0 and removed in v0.21.0 (shortened -from v0.22.0; [support policy](../support-policy.md#the-flat-layout-is-removed)). `pharn` 0.20.x is the -last version that moved a flat install to `pharn/`. - -- **An install recorded at `flat`.** `update` (and `--dry-run`, `--json`) exits 1 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](init.md)). It never moves or deletes the old top-level - copies: the ones `pharn` recorded stay recorded, and `pharn status` and `pharn update` list them under - `ORPHANED` until you delete them by hand (or `pharn uninstall` removes the unchanged ones). -- **A fetched pharn-oss in the flat layout.** Every such release predates `pharn-install.json`, so the - fetch refuses it and nothing is written. - -## The root-footprint migration - -Removed in v0.21.0 (shortened from v0.22.0); `pharn` 0.20.x is the last version that ran it. An install -made from a pharn-oss older than 7.0.0 left `THREAT-MODEL.md` and `LIMITS.md` at the project root; earlier -`pharn` releases deleted those root copies once the `pharn/` copies had landed, printed a -`ROOT MIGRATION` note and hinted at moving a root `memory-bank/` or `pharn.spec-template.md`. Now: - -- `update` installs `pharn/THREAT-MODEL.md` and `pharn/LIMITS.md` and leaves the root copies alone. A root - copy `pharn` recorded is listed under `ORPHANED` (with its state: unchanged or edited) and keeps its - record, like any file upstream stopped shipping; delete it by hand, or let `pharn uninstall` remove it - while it still equals its record. -- Root `memory-bank/`, `pharn.spec-template.md` and `.pharn/` are never moved, copied, deleted or - mentioned, and `.gitignore` gets no replacement hint for an old `.pharn/` line. -- `--dry-run --json` reports `plan.rootMigration` as the constant `null`. - -## A surface pharn-oss does not ship - -Every product surface `update` installs is optional on the way in, as for [`init`](init.md#a-surface-pharn-oss-does-not-ship): -a clone 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: nothing on disk was -left behind by it, so it does **not** withhold the `skillsVersion` bump. Every run plans, so an -up-to-date run names it too; [`pharn status`](status.md) 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. - -## `.gitignore` - -Like [`init`](init.md#gitignore), every applied `update` makes sure your root `.gitignore` covers -`pharn/.run/` (PHARN's runtime scratch) and `pharn/.backup/` (these 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, so an -install made before 0.16.0 gets the lines on its next `update`, 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`. - -## `.prettierignore` - -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](init.md#prettierignore) — 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, so an install made before 0.17.0 — or a project that adopted Prettier later -— gets them on the next `update`, 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`. - -## What is protected by default - -- `.claude/settings.json` — your Claude Code configuration. `init` writes it only when absent; `update` - **never** touches it at all (not even with `--force` — it is not in the install manifest). When `init` - created it, `update` keeps the hash `init` recorded for it in `pharn.records.json` while the file - exists, so [`uninstall`](uninstall.md) can 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. It does - compare the hooks of that file and `.claude/settings.local.json` with the fetched upstream ones. It - prints a `HOOKS` note naming 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 under - `REPLACE`, with your current line, so you swap it rather than add a second one; the rest are - listed under `ADD`. The note also names hooks wired only in `settings.local.json`, which run for you but - not for your teammates. See [status](status.md#what-is-intentionally-excluded) for the full rules. -- `pharn/CONSTITUTION.md` — protected like every other manifest path: if you have edited it, it is a `modified` - skip by default. `--force` overwrites it too, after copying the current bytes to `pharn/.backup/`. - (Before 0.4.0 `update` silently overwrote a hand-edited constitution despite docs claiming otherwise — - that is fixed.) +- Notes a run prints: [the executable unit](../reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none) (`held`), [orphaned files](../reference/update-advanced.md#orphaned-files) (`ORPHANED`), [the `models` block](../reference/update-advanced.md#the-models-block) (`MODELS`), [a surface pharn-oss does not ship](../reference/update-advanced.md#a-surface-pharn-oss-does-not-ship) (`NOT SHIPPED`), [what is protected by default](../reference/update-advanced.md#what-is-protected-by-default) (`HOOKS`), [the features README at the project root](../reference/update-advanced.md#the-features-readme-at-the-project-root). +- Install states: [when pharn cannot read a capability upstream](../reference/update-advanced.md#when-pharn-cannot-read-a-capability-upstream) (`frozenCapabilities`), [missing files at the same skills version](../reference/update-advanced.md#missing-files-at-the-same-skills-version), [a records store from an interrupted run](../reference/update-advanced.md#a-records-store-from-an-interrupted-run), [no usable records store](../reference/update-advanced.md#no-usable-records-store), [an install recorded at the flat layout](../reference/update-advanced.md#an-install-recorded-at-the-flat-layout). +- Files it touches: [`.gitignore`](../reference/update-advanced.md#gitignore), [`.prettierignore`](../reference/update-advanced.md#prettierignore), [writes replace the file](../reference/update-advanced.md#writes-replace-the-file). +- Refusals: [`pharn is too old for the current pharn-oss`](../troubleshooting.md#pharn-is-too-old-for-the-current-pharn-oss) (`MIN_CLI`). ## Related -- [pharn.config.json](../reference/pharn-config.md) — `skillsVersion`, `archetypes`, `capabilities` -- [pharn.records.json](../reference/pharn-records.md) — the per-file hash baseline this command reads -- [status](status.md) — the read-only report of what has drifted -- [add](add.md) +[pharn.config.json](../reference/pharn-config.md) (`skillsVersion`, `archetypes`, `capabilities`) · +[pharn.records.json](../reference/pharn-records.md) (the hash baseline) · [status](status.md) (what has +drifted) · [add](add.md) diff --git a/docs/getting-started.md b/docs/getting-started.md index 82a99713..e541aad2 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -21,10 +21,9 @@ also refuses off a TTY, and `update --yes` is the supported way through in CI.) package prerequisite to satisfy. See [Troubleshooting](troubleshooting.md). PHARN installs **into your existing project**. Just before writing, `pharn init` checks which of its -actual install targets (the selected capability dirs, the product commands/hooks, the contracts, core -and floor dirs, all four trusted docs, pharn's `LICENSE` copy, `pharn/features/README.md`, and -`pharn.config.json`) already exist in your project. If any do, it lists them and asks you to confirm -before overwriting — default **no**; if none do, there is no prompt at all. Your +install targets (the paths in [What you get](#what-you-get), except `pharn.records.json`) already exist in +your project. If any do, it lists them and asks you to confirm before overwriting — default **no**; if +none do, there is no prompt at all. Your `.claude/settings.json` is never overwritten, so it is not part of the check. When your project has none, `init` copies pharn-oss's and lists the hook commands it wires, so you can review what Claude Code will run. @@ -42,7 +41,6 @@ npx @pharn-dev/pharn init ```bash npx create-next-app@latest my-app cd my-app -npx shadcn@latest init [ -d .git ] || { git init && git add -A && git commit -m "init"; } npx @pharn-dev/pharn init ``` @@ -59,18 +57,12 @@ the project root. 1. **Detect archetypes.** The CLI merges your `package.json` dependency names with a bounded, symlink-safe file-tree scan (names only, never file bodies) into an archetype set — `ssr`, `backend`, - `spa`, `lib` (a project may match several, e.g. Next + Express → `ssr` + `backend`). It shows what it - detected, and what triggered each one (e.g. `backend ← src/app/api/`). Detection is **JS/TS-shaped**: - the signals are npm dependency names, `.tsx`/`.jsx` files, and — in a Next.js app only — - `next.config.*`, `app/` route handlers and `app/api`/`pages/api`; a root `api/`, `migrations/` and - database `.sql` files count only when the project has a root `package.json`. A Python, Go or Rust - project without one produces no signal, resolves to `lib`, and receives the universal capabilities - only — the correct outcome, not a failure. A server framework or a runtime database driver - (`express`, `pg`, `prisma`, …) counts as `backend` only under `dependencies` — a devDependency-only - one (a mock server, a test database) does not — while SSR and UI frameworks count under - `devDependencies` too. If the scan stops at its bounds (50,000 entries, 24 directories deep) before - its result is settled, the summary says `detection stopped early`. If detection gets your project - wrong, pass the archetypes yourself: `pharn init --archetype backend` (see [`init`](commands/init.md#choosing-the-archetypes-yourself---archetype)). + `spa`, `lib` (a project may match several, e.g. Next + Express → `ssr` + `backend`) — and shows what + triggered each one (e.g. `backend ← src/app/api/`). Detection is **JS/TS-shaped**: a Python, Go or + Rust project without a root `package.json` resolves to `lib` and receives the universal capabilities, + the correct outcome. The rules are in [Detect archetypes](commands/init.md#3-detect-archetypes); if + detection gets your project wrong, pass the archetypes yourself: `pharn init --archetype backend` (see + [`init`](commands/init.md#choosing-the-archetypes-yourself---archetype)). 2. **Fetch + resolve.** It downloads the newest **verified release** of `pharn-dev/pharn-oss` — a tag pharn-oss creates only after its post-merge CI passed — as a tarball, and selects the capabilities whose `applies` is `universal` or intersects your detected archetypes — skipping the rest with a @@ -100,23 +92,27 @@ surfaces: | `.claude/agents/` | The `pharn-*` subagents (`pharn-review-lens` runs each `/pharn-review` lens); none from a pharn-oss older than 6.64.0 | | `pharn/pharn-contracts/`, `pharn/floor/` | Inter-layer schemas + the floor checkers the commands invoke, as pharn-oss's `pharn-install.json` declares them (no test files) | | `pharn/pharn-core/` | The agnostic mechanism skills the commands cite (the seam resolver + its evals) | -| `pharn/CONSTITUTION.md`, `pharn/ARCHITECTURE.md` | Two of the four trusted spec docs, copied verbatim — see the layout note below | +| `pharn/CONSTITUTION.md`, `pharn/ARCHITECTURE.md` | Two of the four trusted spec docs, copied verbatim | | `pharn/THREAT-MODEL.md`, `pharn/LIMITS.md` | The other two | | `pharn/LICENSE` | PHARN's Apache-2.0 license, copied so a repo you publish carries the grant. Your own root `LICENSE` is never touched | | `pharn/features/README.md` | The product-loop boundary contract the installed commands cite by name | | `pharn.config.json` | `skillsVersion`, commit SHA, detected archetypes, installed capabilities, and the layout | | `pharn.records.json` | Per-file sha256 — skips unproven present edits, restores missing; `--force` overwrites all but `unreadable` | -`.claude/*` is **layout-invariant** — commands, agents, hooks and `settings.json` sit at those paths either -way, and an existing `.claude/settings.json` is never overwritten (a fresh one is copied, and `init` -lists the hooks it wires). Everything else is what the fetched version's `pharn-install.json` declares -(pharn-oss 7.21.0 and later; an older one is refused): the CLI never rewrites a copied file's contents, -and the paths above are the `pharn` layout it installs. The legacy **flat** layout (the same surfaces -at the project root) was removed in v0.21.0: a project still recorded at it is asked to re-run -`pharn init`, which reinstalls at `pharn/` and leaves the old top-level copies for you to delete -([support policy](support-policy.md#the-flat-layout-is-removed)). Each doc is copied only if the -manifest declares it, and `init` says which docs it wrote and warns about any it did not. The layout is -recorded as `layout` in `pharn.config.json`. +These are the paths `pharn` installs, exactly as the fetched pharn-oss's `pharn-install.json` declares +them (pharn-oss 7.21.0 or later); the CLI never rewrites a copied file's contents. How each is written, +and the `.claude/settings.json` rules, are in [`init`](commands/init.md#7-install). + +As you run the workflow, PHARN writes one directory per increment, `pharn/features//`, holding that +increment's `SPEC.md`, `PLAN.md`, `AC-TESTS.md`, `GRILL.md`, `BUILD.md`, `REGRESSION.md`, `VERIFY.md`, then +`SHIP.md` + `BRIEFING.md` (`/pharn-ship`) or `LOOP.md` (`/pharn-loop`), a `RUN-REPORT.md`, and the +machine-readable records beside them (`AC-TESTS.lock.json`, `cost.json`, the `*-report.json` files). Those +are the durable record; commit them. `pharn/.run/` (runtime scratch) and `pharn/.backup/` are not, and +[`init`](commands/init.md#gitignore) adds them to your `.gitignore`; `pharn/.lock*` is a transient file, so +add it yourself if you like. An install made from a pharn-oss older than 7.0.0 may have a `.pharn/` +`.gitignore` line (replace it with `pharn/.run/` yourself) and a root `memory-bank/` or +`pharn.spec-template.md`, which `pharn` never moves: move them to `pharn/memory-bank/` and +`pharn/spec-template.md` (`git mv`), or merge by hand when the `pharn/` copy already exists. See [pharn.config.json](reference/pharn-config.md) and [pharn.records.json](reference/pharn-records.md) for the exact schemas. **Commit both** — they are @@ -127,12 +123,27 @@ your project's PHARN state. 1. Open **Claude Code** in the project directory. 2. Run **`/pharn-spec`** to capture your first feature's intent — it pins the scope and feeds `/pharn-plan`. This is where every run begins: `/pharn-plan` gates on an **Approved**, un-drifted `SPEC.md` and halts without one, so there is no entry point further down the chain. -The pipeline is eight typed stages: `/pharn-spec → /pharn-plan → /pharn-grill → /pharn-test → /pharn-build → /pharn-regress → /pharn-verify → /pharn-ship`. You rarely run them by hand — **`/pharn-ship`** is itself the eighth stage and orchestrates the seven before it in one pass, keeping both human gates: approve the spec before code is written, decide merge/fix/abandon after verification. **`/pharn-loop`** runs the same chain unattended — the model approves the spec and iterates build → regress → verify until green, an iteration cap, or a terminal failure — and leaves the merge/fix/abandon decision to you after the run. From pharn-oss 7.7.0, a full `/pharn-loop` (not `--quick`) also runs **`/pharn-triage`** after the grill: it gives every grill finding one disposition. Since 7.8.0 a `replan` verdict sends the run back to `/pharn-plan` for at most two re-plan rounds, and since 7.9.0 a verdict that still escalates (`spec`, or `replan` with no round left) goes to **`/pharn-supervise`**, a fresh agent that decides `stop` or `proceed-at-risk` — the run goes on, and the escalated findings are named as known risk in the green commit and the run report. Since 7.10.0 it may instead amend the SPEC, once per run (`amend-spec`). The supervisor's decision is one model's judgment, not a check (pharn-oss's `pharn/LIMITS.md` §1d). +The pipeline is eight typed stages, each reading what the previous one produced: + +| Stage | Command | Purpose | +| ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Spec | `/pharn-spec` | Capture feature intent and scope. Stops for your approval. | +| Plan | `/pharn-plan` | Turn the approved spec into an implementation plan, mapping each acceptance criterion to a test (`AC-TESTS.md`). | +| Grill | `/pharn-grill` | Challenge the plan before code is written. | +| Test | `/pharn-test` | Write each acceptance criterion's test before the build, run it, and require it to fail. `/pharn-build` refuses to start without that evidence. | +| Build | `/pharn-build` | Implement an approved increment. | +| Regress | `/pharn-regress` | Look for regressions outside the just-built feature. | +| Verify | `/pharn-verify` | Verify behavior and PHARN floor requirements, including that every acceptance criterion's test now passes. | +| Ship | `/pharn-ship` | Run stages 1-7 in order, then stop at the merge/fix/abandon gate. | + +You rarely run them by hand — **`/pharn-ship`** is itself the eighth stage and orchestrates the seven before it in one pass, keeping both human gates: approve the spec before code is written, decide merge/fix/abandon after verification. **`/pharn-loop`** runs the same chain unattended — the model approves the spec and iterates build → regress → verify until green, an iteration cap, or a terminal failure — commits a green result to a new local branch (never pushed or merged), and leaves the merge/fix/abandon decision to you after the run. From pharn-oss 7.7.0, a full `/pharn-loop` (not `--quick`) also runs **`/pharn-triage`** after the grill: it gives every grill finding one disposition (you can run `/pharn-triage` yourself after a full `/pharn-grill`). Since 7.8.0 a `replan` verdict sends the run back to `/pharn-plan` for at most two re-plan rounds, and since 7.9.0 a verdict that still escalates (`spec`, or `replan` with no round left) goes to **`/pharn-supervise`**, a fresh agent that decides `stop` or `proceed-at-risk` — the run goes on, and the escalated findings are named as known risk in the green commit and the run report. Since 7.10.0 it may instead amend the SPEC, once per run (`amend-spec`). The supervisor's decision is one model's judgment, not a check (pharn-oss's `pharn/LIMITS.md` §1d). **Set up a test runner before your first feature.** `/pharn-test` writes each acceptance criterion's test before the build and requires it to fail, so it needs a `test` script (plus `test:e2e` or `e2e` for end-to-end criteria) whose reporter writes per-test JSON, named under `testResults` in `pharn.config.json`. Without one, `/pharn-test` stops and asks, and `/pharn-loop` ends with `blocked: no-test-runner`. Set the runner up as its own increment (a SPEC with `spec_kind: test-infra`); the reporter setup is in upstream's [Per-test results](https://github.com/pharn-dev/pharn-oss#per-test-results). Two of the installed commands stand on their own, outside the pipeline and `/pharn-loop`: **`/pharn-review`** runs the review lenses in parallel over any code and merges their findings (no stage invokes it), and **`/pharn-memory-promote`** promotes one lesson into `pharn/memory-bank/` through a gated provenance check. +`/pharn-spec` fills PHARN's default SPEC template, or your own if you put one at `pharn/spec-template.md`. The write guard denies Claude Code's edit tools on that path, so edit it yourself; see upstream's [Your own SPEC template](https://github.com/pharn-dev/pharn-oss#your-own-spec-template). + ## Next steps - Review what was written: [pharn.config.json](reference/pharn-config.md) diff --git a/docs/reference/deletes.md b/docs/reference/deletes.md index f5ccccf8..8244b031 100644 --- a/docs/reference/deletes.md +++ b/docs/reference/deletes.md @@ -38,7 +38,7 @@ entry from `pharn.config.json`. Details: [`remove`](../commands/remove.md). - Each file recorded in `pharn.records.json` whose path is one an install writes, that is a regular file reached without a symbolic-linked directory, and whose bytes still equal its record. This - includes [orphans](../commands/update.md#orphaned-files) and `.claude/settings.json` when a fresh + includes [orphans](update-advanced.md#orphaned-files) and `.claude/settings.json` when a fresh `pharn init` created it. - Then each directory those deletes left empty, deepest first, never the project root (a non-recursive delete, so a directory that still holds anything stays). @@ -63,7 +63,7 @@ the entries under the directory it removed. No file is touched. See and only when the lock still names that run. A lock judged stale is moved to `pharn/.lock..`, checked and deleted by the run that moved it; a file of that name that a killed run left behind is never deleted. See - [If the lock outlives its owner](../troubleshooting.md#if-the-lock-outlives-its-owner). + [If the lock outlives its owner](project-lock.md#if-the-lock-outlives-its-owner). - **An empty `pharn/` the lock created.** When `pharn/` did not exist, the lock creates it and deletes it again if it is still empty when the lock is released. - **A write's temp file.** A file `pharn` replaces is first written to `...tmp` beside diff --git a/docs/reference/json-output.md b/docs/reference/json-output.md index 828b1777..f77b320d 100644 --- a/docs/reference/json-output.md +++ b/docs/reference/json-output.md @@ -241,7 +241,7 @@ The outcome is `status`: | `plan.backups` | string array | The files copied to `pharn/.backup//` first (`pharn.config.json` too when `--force` replaces your `models` block). | | `plan.skipped` | `{label, rels}[]` | Skipped files grouped by reason, most actionable first. | | `plan.counts` | `{updated, restored, ok, forced, skipped}` | Totals; never filtered by `--compact`. | -| `plan.executableUnit` | `{blocking, held, missing}` | _Absent when empty._ The [executable-unit hold](../commands/update.md#the-executable-unit-is-upgraded-all-or-none): `blocking` the skipped unit files as `{rel, label}`, `held` the unit files not written because of them, `missing` (absent when empty) the held files not on disk. | +| `plan.executableUnit` | `{blocking, held, missing}` | _Absent when empty._ The [executable-unit hold](update-advanced.md#the-executable-unit-is-upgraded-all-or-none): `blocking` the skipped unit files as `{rel, label}`, `held` the unit files not written because of them, `missing` (absent when empty) the held files not on disk. | | `plan.models` | `{outcome, label, replacedLegacyDefault, backup, conversion, problems, upstreamReasons}` | `outcome` `restored`, `updated`, `ok`, `kept`, `forced`, `upstream-absent` or `upstream-invalid`; `label` the skip label when the block is yours, else `null`; `backup`: `pharn.config.json` copied first. The block itself is not included. | | `plan.hooks` | `Hooks` | The same comparison as `status --json`. `update` never writes your settings files. | | `plan.absentUpstream` | `Absent[]` | _Absent when empty._ | diff --git a/docs/reference/pharn-config.md b/docs/reference/pharn-config.md index 2e10fbf9..3af56e13 100644 --- a/docs/reference/pharn-config.md +++ b/docs/reference/pharn-config.md @@ -1,8 +1,6 @@ # pharn.config.json Written to the project root on a successful `pharn init`, and updated by `pharn add`, `pharn remove` and `pharn update`. -Source: [`pharn-config.ts`](../../src/lib/pharn-config.ts) and -[`install-archetype.ts`](../../src/steps/install-archetype.ts). It is the CLI's record of what it installed. PHARN's commands in your project do **not** read `capabilities` to decide which grillers and lenses run: they scan the capability directories on disk @@ -28,7 +26,7 @@ capability they drop. At run time `/pharn-ship` and `/pharn-loop` read the `mode | `layout` | string | Install layout your files are at: `pharn`. Anything else, or no key, is refused: re-run `pharn init` | | | `models` | object | pharn-oss's per-stage model/effort block ([Models](#models)) | | -`isArchetypeConfig` treats the presence of a `capabilities` array as the marker of an archetype install. +The presence of a `capabilities` array marks an archetype install. A `capabilities` that is present but **not** an array (for example `"capabilities": "x"` or `null`) is a hand-edit error, not a legacy install: `pharn` names it and exits 1 instead of telling you to re-run `pharn init`, which would overwrite the file. An absent `capabilities` is still the pre-archetype @@ -261,7 +259,7 @@ not apply such a block from pharn-oss. every other key pharn writes. - **`pharn update`** treats the block like a file: pharn-oss's block replaces one pharn wrote, and one you changed is kept, with what pharn-oss's rules reject in it listed. See - [update](../commands/update.md#the-models-block). + [update](update-advanced.md#the-models-block). - **`pharn status`** prints every product stage beside the model and effort it resolves to — marked `(default)` when the stage has no entry of its own — under the label above, and lists by name anything pharn-oss's rules reject. See [status](../commands/status.md). @@ -273,7 +271,7 @@ because it is not `pharn`'s schema. `pharn` checks it where it copies, keeps or copy over a corpus of cases and fails on any difference. If pharn-oss's rules move ahead of the copy in your pharn (a new stage, a new alias), `pharn` does not apply the newer block, names what it could not accept, and upgrading `pharn` fixes it. pharn-oss can also require the upgrade with `MIN_CLI` (see -[`pharn is too old for the current pharn-oss`](../commands/update.md#pharn-is-too-old-for-the-current-pharn-oss)). +[`pharn is too old for the current pharn-oss`](../troubleshooting.md#pharn-is-too-old-for-the-current-pharn-oss)). ### The format `pharn` wrote before 0.7.0 @@ -283,7 +281,7 @@ no longer converts it (0.19.x was the last release that did): it is a block phar like any other. `pharn status` lists what they reject, and `pharn update` keeps it unless its record proves `pharn` wrote it. To move to pharn-oss's block, replace yours by hand, or delete the `models` key so the next `pharn update` writes pharn-oss's; `pharn update --force` also replaces it, but -overwrites every other file you edited too. See [update](../commands/update.md#the-models-block). +overwrites every other file you edited too. See [update](update-advanced.md#the-models-block). ## Seam resolution diff --git a/docs/reference/pharn-records.md b/docs/reference/pharn-records.md index b2e765a5..96efd121 100644 --- a/docs/reference/pharn-records.md +++ b/docs/reference/pharn-records.md @@ -2,16 +2,14 @@ A CLI-owned sidecar written next to [`pharn.config.json`](pharn-config.md) at your project root. Its `files` map holds a sha256 per **install-manifest path** — the PHARN-owned surfaces and selected -capabilities collected by `runInstallArchetype` (`collectExpectedInstallPaths`), not every file `pharn` -writes. [`pharn update`](../commands/update.md) compares against it to tell pharn's bytes from your +capabilities an install expects (what the fetched `pharn-install.json` declares, plus your selection), not +every file `pharn` writes. [`pharn update`](../commands/update.md) compares against it to tell pharn's bytes from your edits and refuse to destroy the latter. `pharn.config.json` and this file are excluded from the map. Two entries are not install-manifest paths: `pharn.config.json#/models`, which is not a file — it records the `models` block `pharn` wrote **inside** `pharn.config.json` (see [The `models` block](#the-models-block)) — and `.claude/settings.json`, only when `init` created it (see [`.claude/settings.json`](#claudesettingsjson)). -Source: [`install-records.ts`](../../src/lib/install-records.ts). - **Commit it.** It is part of your project's PHARN state, like `pharn.config.json`. Without a usable store, `update` skips every **present** file that differs (`unverifiable`) but still **restores** missing ones; files identical to upstream are no-ops and have their records refreshed. @@ -92,7 +90,7 @@ whitespace). So re-indenting your config is not an edit, while reordering the bl `init` writes it with the block; `update` rewrites it when it writes pharn-oss's block, and carries it unchanged when it keeps yours; `add` and `remove` carry it untouched. `update` compares your block against it exactly as it compares a file against its record — see -[update](../commands/update.md#the-models-block). It is only compared, never used as a path, and a +[update](update-advanced.md#the-models-block). It is only compared, never used as a path, and a store without it reads the block as `unrecorded`. ## When the store is ignored (fail-closed) @@ -149,7 +147,7 @@ Skipped files keep their previous entry, since it still describes what `pharn` w **A file upstream stopped shipping that is still in your project keeps its entry**, with its old hash, until you delete it. That entry is what lets `update` and `status` keep listing the file as an -[orphan](../commands/update.md#orphaned-files) — `UNCHANGED` while its bytes still match, `EDITED` once +[orphan](update-advanced.md#orphaned-files) — `UNCHANGED` while its bytes still match, `EDITED` once they do not. Once the file is gone, the next `update` drops the entry. If upstream ships the path again, the entry makes it a clean upgrade instead of an `unrecorded` skip. The entries of a capability `update` drops from your config are not kept: those files are named by the membership change, not as diff --git a/docs/reference/project-lock.md b/docs/reference/project-lock.md new file mode 100644 index 00000000..3bf81bd6 --- /dev/null +++ b/docs/reference/project-lock.md @@ -0,0 +1,90 @@ +# The project lock + +`init`, `add`, `remove`, `update` and `uninstall` take a single-writer lock, `pharn/.lock`, before they +read `pharn.config.json` or touch the network, and hold it to their last write, across their prompts. A +second writer refuses rather than queues (see +[Another pharn process is running](../troubleshooting.md#another-pharn-process-is-running)). `--dry-run`, +`pharn list` and `pharn status` never take it, so `pharn status --strict` stays runnable in CI while an +update is in flight. The refusal always says the holder "may be waiting for input in another terminal": +the lock does not record whether its holder sits at a prompt. + +## Why it exists + +Two concurrent runs do not merely race on a file: they corrupt the drift baseline. Process A overwrites a +file; process B, which planned against the pre-A snapshot, overwrites it again and records its own hash; A +then persists its records and config last, recording a hash for bytes B replaced. +[`pharn.records.json`](pharn-records.md) then disagrees with disk, and nothing in it shows that, so `update` +loses its ability to tell "pharn wrote this" from "you edited this". + +## If the lock outlives its owner + +Every writing command holds the lock across its prompts, so a walked-away prompt (`init`'s summary or +overwrite question, `update`'s or `uninstall`'s confirmation, the `add` or `remove` picker) blocks other +writers in that project until it is answered or cancelled. That is deliberate, as git holds its index lock: +the command plans once, and what you confirm is what it writes. An edit you make while a prompt is open is +never lost: `init` backs the file up before it overwrites it, and `update` stops before writing anything +(see [update: edits made while it waits](../commands/update.md#edits-made-while-update-waits-for-your-answer)). + +An interrupted run releases the lock on its way out. That covers Ctrl-C, and a `timeout` or `docker stop`, +which arrive as `SIGINT` and `SIGTERM`. The run still exits 130 or 143 and prints that the project may be +partially updated. Three things cannot release the lock: + +- a run that is `SIGKILL`ed; +- one that loses power; +- one ended by a hangup (`SIGHUP`, a closed terminal). + +The hangup case is deliberate: listening for it would override `nohup`, and a `nohup pharn update` would +then stop mid-write. `pharn` breaks such a lock by itself when any of these hold: + +- the file is missing, unreadable, or not a well-formed lock payload, and has not been modified in the last + 10 seconds (a lock is briefly empty while its owner writes it); +- its start time is more than five minutes in the future (no running `pharn` writes that; it is treated like + a malformed payload); +- it comes from **another host** and is more than six hours old; +- it names a pid on **this** host that is no longer running; +- it comes from **this** host and started before this host last booted. + +A lock from **this** host is never broken by age: while its pid is running, `pharn` refuses, however long +ago it started (a prompt left open over lunch keeps the project). A lock from **another host** is only +retired by age, since a pid means nothing across machines. If you are certain nothing is running, deleting +`pharn/.lock` is safe and is the documented escape. + +**A recycled pid keeps a dead run's lock alive until the next reboot.** "No longer running" is checked by +asking the operating system whether that pid exists. If the run that took the lock was killed and its pid +has since been reused by an unrelated process, the lock reads as live, so `pharn` keeps refusing until this +host reboots. If the refusal names a pid that is not a `pharn` process (check with `ps -p `), delete +`pharn/.lock`. + +**The boot check trusts the clock.** On a machine with no battery-backed clock, or one whose clock is +corrected forward by a long way after it boots, a running `pharn` can look as if it started before boot, and +another run on the same machine may then break its lock; corrections under five minutes are tolerated. A +clock set **back** by more than five minutes makes a running lock look as if it started in the future, and +it is then broken after 10 seconds like a malformed one. "This host" means the machine's hostname: if it +changes while `pharn` runs (macOS can rename itself when the network changes), the lock is treated as one +from another host (retired after six hours) and the run cannot remove it when it finishes, so delete +`pharn/.lock` yourself if no `pharn` is running. + +**A directory named `pharn/.lock`** is never a lock (`pharn` does not create one), so it is refused with its +own message rather than broken: + +```text +pharn/.lock is a directory, not a pharn lock file. pharn will not move or delete it, and cannot take the project lock while it is there. +Remove it yourself (or rename it) and re-run. +``` + +**A file named `pharn/.lock..`** is what is left when a `pharn` run is killed (`kill -9`, a power +cut) in the instant it breaks a stale lock: it moves the old lock to that name, checks it, and deletes it. +`pharn` never reads such a file and never deletes a name it did not just create, so it stays until you +delete it. It is safe to delete when no `pharn` command is running. + +**Do not run two `pharn` versions in one project at the same time.** `pharn` 0.13.0 and older lock a +different file, so neither sees the other's lock. + +**`pharn` must be a real directory.** The lock, the backups and the install all live under `pharn/`, which a +writing command creates when it is missing (and removes again if nothing ended up in it). A `pharn` that is +a symbolic link, or a regular file, is refused before anything is written: + +```text +pharn is a symbolic link. pharn keeps its lock, backups and install under pharn/ and will not write through a link that may point outside the project. +Replace it with a real directory and re-run. +``` diff --git a/docs/reference/update-advanced.md b/docs/reference/update-advanced.md new file mode 100644 index 00000000..cb558f9e --- /dev/null +++ b/docs/reference/update-advanced.md @@ -0,0 +1,317 @@ +# update: less common situations + +The states and notes of [`pharn update`](../commands/update.md) that most runs never meet. Each section +is linked from the command page. + +## The executable unit is upgraded all or none + +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: + +```text +◇ 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 `skillsVersion` is **withheld**, as for any skip. +- When every file that blocked the unit (and every other skipped file) is one **you edited** (`modified` or + `unrecorded`), the version the run applied is recorded as `pendingSkillsVersion`, and + [`pharn add`](../commands/add.md) installs at it: it writes capability directories only, which are outside + the unit and were upgraded anyway. When any blocker is something else (`unverifiable` because there is no + usable record store, or `unreadable`), nothing is recorded, and `pharn add` refuses until the update can + finish. `pharn update --dry-run` shows 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: `pharn` never 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 status`](../commands/status.md) reports + 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. +- `--force` never holds. It backs up the skipped files and writes the whole set (an `unreadable` path 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](json-output.md#update)). + +## 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 (see +[What PHARN deletes](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 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 `). +``` + +- **`UNCHANGED`**: the file still has the exact bytes `pharn` recorded 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. `pharn` does 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`](../commands/uninstall.md) 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](../getting-started.md#what-you-get). + +**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`](../commands/status.md#orphaned-files), 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 `pharn` has 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 `CAPABILITIES` note, and its directory is deleted (see + [Dropped capabilities are deleted](../commands/update.md#dropped-capabilities-are-deleted)). +- Anything outside the paths an install can write (`.claude/commands/pharn-*.md`, `.claude/hooks/*.cjs` or + `*.mjs`, the capability directories, `pharn-contracts/`, `pharn-core/`, the floor directory, the trusted + docs, the PHARN license and the features `README.md`), even if a hand-edited `pharn.records.json` names 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. + +## When pharn cannot read a capability upstream + +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: + +```text +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.** `pharn` will not copy content it could not + validate. +- **Your `pharn.config.json` entry is kept**, reported as `KEPT — pharn could not read these upstream this +run`. +- **Everything else updates normally**, including the skills version, so the next + [`pharn add`](../commands/add.md) is 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`](../commands/remove.md). + +## The `models` block + +`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](pharn-config.md#models)). `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`](pharn-records.md#the-models-block). + +**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. + +## Missing files at the same skills version + +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`](../commands/status.md) 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`](../commands/status.md) reports it. A capability you removed with +[`pharn remove`](../commands/remove.md) is restored too when your archetypes still select it (see +[Removing an auto-selected capability](../commands/remove.md#removing-an-auto-selected-capability)). + +## A records store from an interrupted run + +[`pharn.records.json`](pharn-records.md) 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](pharn-records.md#the-stamp-is-not-a-gate). + +## No usable records store + +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 status` shows the same set), revert what you did not intend to keep, + and re-run `pharn 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. + +## An install recorded at the flat layout + +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](../support-policy.md#the-flat-layout-is-removed)). +`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](../commands/init.md)). It never moves or deletes the old top-level copies: the ones +`pharn` recorded stay listed under [`ORPHANED`](#orphaned-files) 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. + +## A surface pharn-oss does not ship + +Every product surface `update` installs is optional on the way in, as for +[`init`](../commands/init.md#a-surface-pharn-oss-does-not-ship): 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`](../commands/status.md) 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. + +## The features README at the project root + +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`. + +## `.gitignore` + +Like [`init`](../commands/init.md#gitignore), 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`. + +## `.prettierignore` + +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](../commands/init.md#prettierignore): 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`. + +## What is protected by default + +- **`.claude/settings.json`**, your Claude Code configuration. `init` writes it only when absent; `update` + **never** touches it (not even with `--force`: it is not in the install manifest). When `init` created it, + `update` keeps the hash `init` recorded for it in `pharn.records.json` while the file exists, so + [`uninstall`](../commands/uninstall.md) can 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 `HOOKS` note.** `update` compares the hooks of `.claude/settings.json` and + `.claude/settings.local.json` with 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 under `REPLACE`, with your current line, so you swap it rather than add a second one; the rest are + listed under `ADD`. The note also names hooks wired only in `settings.local.json`, which run for you but not + for your teammates. See [status](../commands/status.md#what-is-intentionally-excluded) for the full rules. +- **`pharn/CONSTITUTION.md`** is protected like every other manifest path: if you have edited it, it is a + `modified` skip by default. `--force` overwrites it too, after copying the current bytes to + `pharn/.backup/`. + +## Writes replace the file + +`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. diff --git a/docs/support-policy.md b/docs/support-policy.md index fb753298..cf15ecf9 100644 --- a/docs/support-policy.md +++ b/docs/support-policy.md @@ -32,7 +32,7 @@ From v0.21.0, `pharn update`, `add`, `remove`, `list`, `status` and `uninstall` | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | v0.20.0 | A root `.pharn.lock` left by `pharn` 0.13.0 or older, the notice about a root `.pharn-backup/` directory (`pharn` never deletes it; move what you need and delete it yourself), and `pharn update`'s `.gitignore` hints for those two names. The `models` block format `pharn` wrote before 0.7.0 is no longer converted by `update`. | | v0.21.0 | `init` no longer writes `"modules": []` into `pharn.config.json`, so `pharn` 0.19.x and older cannot read a config that 0.21.0 or later wrote (0.20.0 is the oldest that can). The unused fields older configs carry (`modules`, `constitution`, `installedSkills`, `stackAnswers`, `isMultiTenant`) still load, and are dropped the next time `pharn` writes the file. Fetching a pharn-oss older than 7.21.0, which ships no `pharn-install.json` (so also one older than 7.0.0, or one in the `flat` layout): `pharn` refuses it, naming `--ref main`. | -| v0.21.0 | Also: the `flat` layout (its deprecation shortened from v0.22.0 by the maintainer; [above](#the-flat-layout-is-removed)), and the root-footprint migration of installs made from a pharn-oss older than 7.0.0: their root `THREAT-MODEL.md` and `LIMITS.md` are left in place and listed as orphans ([details](commands/update.md#the-root-footprint-migration)). | +| v0.21.0 | Also: the `flat` layout (its deprecation shortened from v0.22.0 by the maintainer; [above](#the-flat-layout-is-removed)), and the root-footprint migration of installs made from a pharn-oss older than 7.0.0: their root `THREAT-MODEL.md` and `LIMITS.md` are left in place and listed as orphans ([details](reference/update-advanced.md#orphaned-files)). | ## Related diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 2a6e49b6..661fe462 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,251 +2,137 @@ ## Exit codes -| Situation | Exit code | -| ------------------------------------------------------------------------------------------------------- | --------- | -| Prerequisite failure (no `.git`, or `init` / `update` on a Node older than 24.2.0) | 1 | -| Capability fetch / install failure | 1 | -| No verified pharn-oss release could be resolved (none published, unreachable, rate-limited) | 1 | -| `update --ref latest` on an install ahead of the newest verified release (nothing changed) | 0 | -| `update` on an install ahead of pharn-oss `main`, after `main` moved back (nothing changed) | 0 | -| An invalid `--ref` value | 1 | -| Unknown command | 1 | -| Unknown option, an option the command does not take, or an unexpected extra argument | 1 | -| A value on an on/off option (`--json=false`), or `--ref` / `--archetype` given twice | 1 | -| `add` / `update` / `remove` / `list` / `status` with no `pharn.config.json` (or a pre-archetype config) | 1 | -| `status --strict` found a [strict condition](commands/status.md#strict-conditions) | 1 | -| `init` or `update` run without an interactive terminal (and `add`/`remove` with no name) | 1 | -| `init --yes` in a project where a file it would write already exists (nothing written) | 1 | -| `init --dry-run` printed its plan (nothing was written) | 0 | -| Another `pharn` process holds the project lock (`pharn/.lock`) | 1 | -| The fetched version declares a `MIN_CLI` newer than the installed CLI | 1 | -| `add` refused on a skills-version or layout mismatch | 1 | -| `update` completed but skipped files it could not verify | 0 | -| `update --dry-run` printed its plan (whatever it contains; nothing was written) | 0 | -| `update --force` aborted because a backup could not be written | 1 | -| `uninstall` refused, or stopped part-way (see [`uninstall`](commands/uninstall.md)) | 1 | -| `uninstall` with no `pharn.config.json` at all (nothing to uninstall) | 0 | -| User cancel at summary, or overwrite declined | 0 | -| Successful install | 0 | +| Situation | Exit code | +| ------------------------------------------------------------------------------------------------------- | ---------- | +| Successful run; `init --dry-run` or `update --dry-run` printed its plan (nothing written) | 0 | +| User cancel at a prompt, or overwrite declined | 0 | +| `update` completed but skipped files it could not verify | 0 | +| `update` on an install ahead of its source (newest release, or `main` after it moved back) | 0 | +| `uninstall` with no `pharn.config.json` at all (nothing to uninstall) | 0 | +| Prerequisite failure (no `.git`, or `init` / `update` on a Node older than 24.2.0) | 1 | +| Capability fetch / install failure, or no verified pharn-oss release could be resolved | 1 | +| The fetched version declares a `MIN_CLI` newer than the installed CLI | 1 | +| Unknown command, unknown or unsupported option, unexpected argument, invalid `--ref` value | 1 | +| A value on an on/off option (`--json=false`), or `--ref` / `--archetype` given twice | 1 | +| `add` / `update` / `remove` / `list` / `status` with no `pharn.config.json` (or a pre-archetype config) | 1 | +| `status --strict` found a [strict condition](commands/status.md#strict-conditions) | 1 | +| `init` or `update` without an interactive terminal (and `add`/`remove` with no name) | 1 | +| `init --yes` in a project where a file it would write already exists (nothing written) | 1 | +| Another `pharn` process holds the project lock (`pharn/.lock`) | 1 | +| `add` refused on a skills-version mismatch | 1 | +| `update --force` aborted because a backup could not be written | 1 | +| `uninstall` refused, or stopped part-way (see [`uninstall`](commands/uninstall.md)) | 1 | +| Interrupted by Ctrl-C (`SIGINT`) or `SIGTERM` (a `timeout`, `docker stop`); the project may be partial | 130 or 143 | + +## Common problems + +| Symptom | See | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| `update` listed files under `SKIPPED` or `held` | [`pharn update` skipped my files](#pharn-update-skipped-my-files) | +| `Another pharn process is writing to this project` | [Another pharn process is running](#another-pharn-process-is-running) | +| `No pharn.config.json found. Run pharn init first.` | [`add` / `update` say to run init first](#add--update-say-to-run-init-first) | +| `Could not resolve the latest verified … release` | [No verified release could be resolved](#no-verified-release-could-be-resolved) | +| `Failed to fetch`, a timeout, or a proxy notice | [Capabilities could not be fetched](#capabilities-could-not-be-fetched) | +| The wrong archetypes were detected | [Detection picked the wrong archetype](#detection-picked-the-wrong-archetype) | +| `Unknown option` / ``Unsupported option for `` `` | [Unsupported option for this command](#unsupported-option-for-this-command) | +| Your Prettier check fails on PHARN's files | [My Prettier check fails on PHARN's files](#my-prettier-check-fails-on-pharns-files) | ## Node version -One Node floor applies to the CLI and to what it installs: **Node 24.2.0 or newer**. - -- **CLI (`@pharn-dev/pharn`):** `engines.node` is `>=24.2.0`. npm/npx only warns about it by default (`EBADENGINE`), so `pharn init` and `pharn update` check it themselves, first, before the git check, any prompt or any network call. On an older Node (or one whose version string cannot be read) they print the required and the current version, exit **1**, and write nothing. `pharn status` prints the floor and the running Node in a `NODE` note and flags a mismatch; it never fails over one, `--strict` included. `pharn add`, `remove` and `list` do not check. -- **Installed floor (`pharn/floor/*.mjs`):** pipeline checkers gate on `import.meta.main`. On Node older than 24.2 a guarded tool used to exit **0** without running its checks — a silent false green — so since pharn-oss 6.50.0 they refuse to run there instead (one stderr line, exit **2**). - -If a `/pharn-*` stage fails with that refusal, check `node -v` in the environment where Claude Code runs your gates and upgrade to **24.2.0 or newer**. CI smoke-tests the packed CLI on exactly 24.2.0. +The CLI and what it installs need **Node 24.2.0 or newer**. `pharn init` and `pharn update` check it first +(npm only warns about `engines.node`), and on an older Node, or one whose version cannot be read, print +`pharn init requires Node 24.2.0 or newer, and this is Node …` (or `pharn update …`), exit **1** and write nothing. `pharn status` +shows the floor in a `NODE` note and never fails over it; `add`, `remove` and `list` do not check. The +installed checkers (`pharn/floor/*.mjs`) refuse to run on an older Node (one stderr line, exit **2**): if a +`/pharn-*` stage fails that way, check `node -v` where Claude Code runs your gates. ## Streams -Error-level messages go to **stderr**; normal output (notes, summaries, prompts, spinners, the -`Cancelled.` line) goes to **stdout**. So the two can be captured separately: - -```bash -pharn update --yes > update.log 2> errors.log -``` - -On success, `pharn list --json` writes exactly one inventory object to stdout and nothing else, so -`pharn list --json | jq .` parses cleanly. On **any** failure — a missing config, a pre-archetype -config, or an argv refusal such as `pharn list --json --bogus` — stdout is **empty**, the diagnostic -goes to stderr, and the exit code is 1. So stdout is either one object or nothing; it is never a -half-written object or an error string. `pharn status --json` keeps the same contract (one report or -nothing), with one addition: with `--strict`, a finding still prints the report and exits 1 — see -[`pharn status`](commands/status.md#json-output). So does `pharn update --dry-run --json`, which prints -the plan (or the `up-to-date` outcome — a plan that changes nothing — or `ahead-of-release` / `ahead-of-main`, as its `status` field, with `plan: null`) and exits 0 — see -[`pharn update`](commands/update.md#json-output) — and `pharn init --dry-run --json`, which prints the -install plan and exits 0 — see [`pharn init`](commands/init.md#json-output). For both, `--json` implies -`--dry-run`, so `pharn update --json` and `pharn init --json` (or a bare `pharn --json`) print the plan too; -`update --compact` (which leaves the unchanged files out of the plan's file list) implies `--json`. - -Cancelling a prompt is a **success** (exit 0), not an error — its message stays on stdout. - -That holds for **every** fatal, the prerequisite failure included: it is reported as an error, on -stderr, with exit 1. (Through `0.3.2` that one message was rendered through the cancel formatter and -landed on stdout, so a run gated on stderr alone found an empty file.) +Error-level messages, every fatal included, go to **stderr**; notes, summaries, prompts, spinners and +`Cancelled.` go to **stdout** (`pharn update --yes > update.log 2> errors.log`). A `--json` command prints +exactly one object on stdout, or nothing on a failure (exit 1); `status --json --strict` still prints its +report when it exits 1 (see [JSON output](reference/json-output.md)). Cancelling a prompt exits 0. ### Colour -`pharn` colours its output only on a terminal, by Node's own rule — the same one its prompts and boxes -use, so the two never disagree: - -- **`FORCE_COLOR` set**: colour is on for `1`, `2`, `3`, `true` or the empty string — even when stdout is - piped — and off for `0` or `false`. `NO_COLOR` is then ignored. -- **`FORCE_COLOR` unset**: colour only on a colour-capable terminal. `NO_COLOR`, `NODE_DISABLE_COLORS` - and `TERM=dumb` each turn it off; `CI` by itself turns nothing on. - -So a piped CI log stays plain unless you set `FORCE_COLOR=1`. (Before 0.13.0, `pharn`'s own text turned -colour on whenever `CI` was set or `FORCE_COLOR` held any value, `0` included, so a piped log could carry -raw `\x1b[…m` sequences.) +Colour follows Node's own rule, the one `pharn`'s prompts use. With `FORCE_COLOR` set, it is on for `1`, +`2`, `3`, `true` or empty (even when piped) and off for `0` or `false`, and `NO_COLOR` is ignored. With it +unset, colour is on only on a colour-capable terminal, and `NO_COLOR`, `NODE_DISABLE_COLORS` or `TERM=dumb` +turn it off; `CI` alone turns nothing on. A piped CI log stays plain unless you set `FORCE_COLOR=1`. ## `pharn update` skipped my files -By default, `update` skips **present** PHARN-owned files it cannot prove are untouched (missing -expected files are still restored). It prints each skipped file under one of four labels (plus `held`, [below](#update-held-the-floor-hooks-and-commands-executable-unit)): - -- **`modified`** — you edited it after `pharn` wrote it. -- **`unrecorded`** — `pharn` has no record of writing that path. -- **`unverifiable`** — there is no usable `pharn.records.json` (absent, malformed, or from a newer - schema), so present differences cannot be proven. A store whose `skillsVersion`/`commit` stamp - disagrees with the config is still usable ([why](reference/pharn-records.md#the-stamp-is-not-a-gate)). Every install created before - `pharn` 0.4.0 hits this once for differing files; **missing** files are still restored. -- **`unreadable`** — something that is not a regular readable file sits at the expected path (a - symlink, a directory, an unreadable file, or a path under a symlinked parent). This is the one - bucket `--force` **cannot** clear; the run says so explicitly. Fix the path by hand. +`update` skips a **present** PHARN-owned file it cannot prove is untouched (a missing one is restored): -Exit code is **0** — this is the designed outcome, not a failure. To overwrite them anyway: +- **`modified`**: you edited it after `pharn` wrote it. +- **`unrecorded`**: `pharn` has no record of writing that path. +- **`unverifiable`**: there is no usable `pharn.records.json` (absent, malformed, or from a newer schema; a + stamp that disagrees with the config is fine, [why](reference/pharn-records.md#the-stamp-is-not-a-gate)). +- **`unreadable`**: a symlink, a directory, an unreadable file or a path under a symlinked parent sits + there. `--force` cannot clear it (`--force cannot clear the UNREADABLE paths above.`): fix it by hand. -```bash -pharn update --force # backs up each skipped file to pharn/.backup//, then overwrites -``` - -Files already identical to upstream are left alone (`ok`) — line endings aside, see -[Line endings](#line-endings-windows-coreautocrlf). `--force` overwrites the `modified`, -`unrecorded` and `unverifiable` buckets only — `unreadable` paths are refused with -`--force cannot clear the UNREADABLE paths above.` and must be fixed by hand. - -A run with skips deliberately leaves `skillsVersion` at the previous value, so `pharn status` keeps -showing an update as available and the next `pharn update` still has work to do. See -[update](commands/update.md) for the full decision table. +That is the designed outcome: exit **0**, and `skillsVersion` stays where it was, so `pharn status` keeps +showing an update. `pharn update --force` overwrites the first three, backing each up to +`pharn/.backup//` first. See the [decision table](commands/update.md#the-decision-table). ### `update` held the floor, hooks and commands (`EXECUTABLE UNIT`) -The floor checkers, the hooks and the `pharn-*` commands run together, so an update to a new skills -version writes them all or none. If one of them is skipped (most often an edited floor checker or a -command whose `model:` line you changed), the others are listed under **`held`**: they are not written -either, and stay at the version you had. Before 0.18.0, `update` wrote the new files beside the skipped -one, and a new checker could fail on import against an old sibling. - -The `EXECUTABLE UNIT` note names the files that blocked it. The run exits **0**, and the recorded version -stays where it was. To finish the upgrade, either revert those files to what `pharn` installed and run -`pharn update` again, or let `pharn` replace them: - -```bash -pharn update --force # backs up the blocking files to pharn/.backup//, then writes the whole set -``` - -`pharn update --dry-run` shows the same note without writing anything. See -[The executable unit](commands/update.md#the-executable-unit-is-upgraded-all-or-none). +The floor checkers, hooks and `pharn-*` commands run together, so a new skills version writes them all or +none. If one is skipped (an edited checker, a command whose `model:` line you changed), the rest are +**`held`** at your version, named in an `EXECUTABLE UNIT` note, exit 0. Revert the blockers and re-run, or +use `--force`. See [the executable unit](reference/update-advanced.md#the-executable-unit-is-upgraded-all-or-none). ### `--force` aborted with a backup error -The backup runs to completion before any original is touched, so an abort means **nothing was -overwritten**. Inspect `pharn/.backup` (and `pharn` itself) in your project: - -- **A regular file** named `pharn/.backup` or `pharn` (not a directory) blocks the backup directory - from being created — **move or rename** it, then re-run. Do not delete it until you have confirmed - it is not something you need. -- **A symlink** at `pharn/.backup` or `pharn` — `pharn` refuses to write backups through it. Confirm - that path is the one named in the error, then remove or replace the symlink and re-run. - -A symlink in a source file's path (or one of its parent directories) is also rejected; the error names -the component. +The backup completes before any original is touched, so **nothing was overwritten**. A regular file named +`pharn/.backup` or `pharn` blocks the backup directory: move or rename it (do not delete it before checking you do not need it), then re-run. A symlink at either +path, or in a source file's path, is refused (the error names it): replace it, then re-run. ### `add`, `remove`, `update` and `init` write backups too -`pharn/.backup//` is not only an `update --force` artefact. Before `pharn add` copies a -capability, it compares each destination file against the clone and copies every one that **differs** -into the same backup directory — so re-adding a capability whose files you edited never loses those -edits. Identical files (line endings aside) are not drift and are not backed up. Everything in -[`--force` aborted with a backup error](#--force-aborted-with-a-backup-error) applies to `add` -verbatim, including the abort-with-nothing-touched contract. - -Before `pharn remove` deletes a capability directory, it copies every file in it that is not recorded in -`pharn.records.json` at its current hash — files you added, files you edited, and every file when the -store is absent or unusable — into the same backup directory. A backup failure makes `remove` exit 1 -having deleted nothing. See -[What is backed up before the delete](commands/remove.md#what-is-backed-up-before-the-delete). - -`pharn update` does the same — even without `--force` — before it deletes the directory of a -capability it drops from `pharn.config.json`, in the same one backup directory as any `--force` -copies. A backup failure makes `update` exit 1 having deleted and written nothing. See -[Dropped capabilities are deleted](commands/update.md#dropped-capabilities-are-deleted). A re-run -`pharn init` does the same for the capabilities it drops, in the one backup it makes before -overwriting — see [`init`](commands/init.md#dropped-capabilities-are-deleted). - -`add` also **refuses outright** — writing nothing, exit 1 — when a destination path crosses a -symlinked directory, naming the offending component: - -```text -⚠ Refusing to add a11y: `pharn/pharn-pipeline/grillers/a11y/evals` in your project is a symlink. -``` - -That is deliberate rather than defensive: the copy would write straight through the link and replace -bytes outside your project, while the backup could not save them. Replace the symlink with a real -directory (or move it aside) and re-run. +`add` backs up every destination file that **differs** from the clone before it copies, and refuses (exit 1, +nothing written) when a destination crosses a symlinked directory, naming it: +``⚠ Refusing to add a11y: `pharn/pharn-pipeline/grillers/a11y/evals` in your project is a symlink.`` +(the copy would write through it): replace it with a real directory, or move it aside. +`remove`, `update` and a re-run `init` back up every file of a capability directory they delete that is not +recorded at its current hash ([remove](commands/remove.md#what-is-backed-up-before-the-delete), +[update](commands/update.md#dropped-capabilities-are-deleted), [init](commands/init.md#dropped-capabilities-are-deleted)). +A failed backup deletes and writes nothing. ## My Prettier check fails on PHARN's files -pharn copies pharn-oss's files as pharn-oss formats them, which is not necessarily how your Prettier -config formats them. Since 0.17.0, `pharn init` and `pharn update` add the lines that keep your check -off those files to `.prettierignore` whenever your project uses Prettier -([how it works](commands/init.md#prettierignore)); `pharn status` shows a `PRETTIER` note when lines are -missing. - -- **Installed with an older pharn?** Run `pharn update`: every run plans, so it adds the lines at the - same skills version too. -- **No `PRETTIER` note, but the check still fails?** Your Prettier setup may not be visible at the - project root (a monorepo package's config, a check run with `--ignore-path` pointing elsewhere or - from a subdirectory). Copy the lines from `pharn update --dry-run` (or an existing `.prettierignore`) - into the ignore file your check reads. -- **Already ran `prettier --write` over them?** They now read as changed, so `pharn update` skips them - ([above](#pharn-update-skipped-my-files)). Once the lines are in place, `pharn update --force` puts - pharn-oss's bytes back, backing up your copies first. -- **The warning says pharn could not update `.prettierignore`** (a symlink, a directory, no - permission)? Add the lines it lists yourself. +`pharn` copies pharn-oss's files as pharn-oss formats them. In a project that uses Prettier, `init` and +`update` add the lines that keep your check off them to `.prettierignore` +([how](commands/init.md#prettierignore)); `pharn status` shows a `PRETTIER` note when lines are missing, and +any `pharn update` adds them. If the check still fails, your Prettier setup may not be visible at the root +(a package config, `--ignore-path`): copy the lines from `pharn update --dry-run` into the file your check +reads. Already ran `prettier --write` over them? Once the lines are in, `pharn update --force` puts +pharn-oss's bytes back, backing up yours. If `pharn` could not write `.prettierignore`, add the lines it lists. ## Line endings (Windows, `core.autocrlf`) -If your project is committed and checked out again with `core.autocrlf=true` (the usual Windows -setting), git rewrites every installed text file with CRLF (`\r\n`) line endings. `pharn` ignores -that difference. Every command that compares files does so with one content hash -([`lib/hash.ts`](../src/lib/hash.ts)) that, for a **text** file, turns each `\r\n` into `\n` before -hashing: `pharn status` drift, the `pharn update` decision, the `pharn add` and `pharn init` backup -scans, the `pharn remove` backup set, which files `pharn uninstall` may delete, and the hashes written to -[`pharn.records.json`](reference/pharn-records.md). So a CRLF checkout of untouched files shows no -drift, `pharn status --strict` passes, and `pharn update` upgrades the files instead of skipping them. - -- **Text or binary.** A file is binary when one of its first 8000 bytes is a NUL byte; every other - file is text. Binary files are compared byte for byte. -- **Only `\r\n` is folded.** A lone `\r` (not followed by `\n`) is kept as it is, so it still counts - as a change. -- **What `pharn` writes.** `pharn` copies upstream's bytes unchanged (upstream ships LF). It does not - convert a file you already have: a CRLF file that is already up to date stays CRLF. -- **Old record stores stay valid.** For a file without `\r\n`, which is every file pharn-oss ships - today, the new hash is the same as the old one. - -**The cost: an edit that only changes line endings is invisible to `pharn`.** If you convert a -PHARN-owned file between LF and CRLF and change nothing else, `pharn status` reports it as unchanged, -`pharn update` may replace it with upstream's file, `pharn add` may overwrite it, and `pharn remove` -and `pharn uninstall` may delete it, each without a backup. Only the line endings can be lost that way; any other change to -the file is still detected as before. - -This is tested by writing CRLF files and by a real `git -c core.autocrlf=true` checkout, on Linux. CI -does not run on Windows (see [Contributing](contributing.md)). +With `core.autocrlf=true`, git checks installed text files out with CRLF. Every comparison `pharn` makes +(`status` drift, the `update` decision, the `add`/`init` backup scans, the `remove` backup set, what +`uninstall` may delete, the [records](reference/pharn-records.md)) hashes a **text** file with each `\r\n` +folded to `\n`, so a CRLF checkout of untouched files shows no drift. A file with a NUL byte in its first +8000 bytes is binary and compared byte for byte; a lone `\r` still counts as a change; `pharn` writes +upstream's LF bytes and does not convert a CRLF file that is already up to date. **The cost:** an edit that +only changes line endings is invisible, so `update`, `add`, `remove` or `uninstall` may replace or delete +such a file without a backup. A record store written before this rule stays valid (a file without `\r\n` +hashes the same). It is tested with a real `git -c core.autocrlf=true` checkout on Linux; CI does not run +on Windows ([Contributing](contributing.md)). ## Prerequisites failed -`pharn init` has two prerequisites — Node >= 24.2.0 and a git repository — and a plain `pharn init` (without `--dry-run` or -`--yes`) needs a third: an interactive terminal. The Node check comes -first: on an older Node, `init` (and `update`) exit 1 with `pharn init requires Node 24.2.0 or newer, and this is Node …` -and write nothing — upgrade Node. A Node whose version string cannot be parsed is refused the same way, because the check -fails closed. (Before 0.8.0 the floor was Node 20.13.0, and on an older Node 20 even `pharn --version` failed at load time -with `does not provide an export named 'styleText'`; that is an unsupported Node now too.) -There is no stack-pack or package prerequisite: archetype detection reads `package.json` names and the -file tree, and installs whatever capabilities apply. - -Off a TTY, a plain `init` or `update` **exits 1** rather than prompting into a dead stream; `update --yes` is -the supported way through in CI. `init --yes` runs off a TTY too, but only installs into a project where none -of its files exists yet — it never answers the overwrite confirmation, so wherever it would overwrite -something it exits 1, lists the files, and points at `pharn init` in a terminal, `pharn init --dry-run` or -`pharn update`. A re-install always would (`pharn.config.json` exists), so there it refuses before -downloading anything, naming only `pharn.config.json`. `init --dry-run` and `update --dry-run` -need no terminal at all: they never prompt and write nothing. +`pharn init` needs Node >= 24.2.0 ([above](#node-version)), a git repository and, for a plain run, an +interactive terminal. Off a TTY a plain `init` or `update` **exits 1**; use `update --yes` in CI. +`init --yes` installs only where none of its files exists yet: wherever it would overwrite it exits 1, +lists the files and points at `pharn init` in a terminal, `--dry-run` or `pharn update`; on a re-install it +refuses before downloading, naming only `pharn.config.json`. `init --dry-run` and `update --dry-run` need no terminal. ### Git not found -The CLI message says "git not found" but the check is for a **`.git` directory**, not the `git` binary: +The check is for a **`.git` directory** here, not the `git` binary (stderr, exit **1**): ```text ■ git not found. @@ -254,115 +140,57 @@ The CLI message says "git not found" but the check is for a **`.git` directory** Then re-run: npx @pharn-dev/pharn init ``` -Printed on **stderr**; exits with code **1**. - -When the current directory is **inside** a git repository but not at its root (for example a monorepo's -`apps/web`), `init` does not suggest `git init`, which would create a repository nested inside yours. It -names the nearest parent directory that has a `.git` instead: - -```text -■ /home/me/mono/apps/web is inside the git repository at /home/me/mono, not at its root. - Run `pharn init` from the repository root (/home/me/mono). -``` - -That parent is found by its `.git` alone. If it is not your project's repository (a dotfiles repository -in your home directory, say) and you do want a separate repository here, create one yourself with the -`git init` command above, then re-run `pharn init`. +Inside a repository but not at its root (a monorepo's `apps/web`), `init` says +`/home/me/mono/apps/web is inside the git repository at /home/me/mono, not at its root.` and asks you to run +it from there. That parent is found by its `.git` alone; if it is not your project's (a dotfiles repository +in your home directory), create a repository here with the `git init` line above. ### My Python / Go / Rust project detected as `lib` -That is the correct outcome, not a failure. Archetype detection is **JS/TS-shaped**: the signals are -`package.json` dependency names, `.tsx`/`.jsx` files, and — in a Next.js app only — `next.config.*`, -`app/` route handlers and `app/api`/`pages/api`. A root `api/`, a `migrations/` directory and `.sql` -files in a database directory count only when the project has a root `package.json`, so a Flask, Go, -Rust, Rails or Laravel project without one produces no signal and resolves to `lib`, which installs the -**universal** capabilities — the ones that apply to any codebase. (The backend capabilities PHARN ships -match JavaScript/TypeScript code.) Use [`pharn add`](commands/add.md) to install any others you want, -or [`--archetype`](#detection-picked-the-wrong-archetype) to install for an archetype anyway. - -A non-JS project that **does** have a root `package.json` — a Laravel or Rails app with a Vite -frontend, or a `package.json` kept only for tooling — counts as a JS project, so its `migrations/` or -`db/*.sql` resolve `backend`. Correct that the same way. +That is correct: detection is **JS/TS-shaped**, so a project without a root `package.json` resolves to +`lib` and gets the **universal** capabilities (one **with** a root `package.json` can resolve `backend` from +its migrations). Add others with [`pharn add`](commands/add.md) or pass +[`--archetype`](#detection-picked-the-wrong-archetype). Rules: [Detect archetypes](commands/init.md#3-detect-archetypes). ### Detection picked the wrong archetype -The install summary shows what triggered each archetype, for example `backend ← src/app/api/` or -`ssr ← next (package.json)`, so you can see why. To install for the archetypes you want instead, re-run -`init` with them: - -```bash -pharn init --archetype spa -pharn init --archetype ssr,backend -``` - -`--archetype` replaces detection (the summary still shows what detection found, marked `(not used)`), -and the archetypes are recorded in `pharn.config.json`, so `pharn update` keeps them. A later re-run of -`pharn init` detects again unless you pass `--archetype` again; when the result differs from what was -recorded, the summary prints `previously recorded: … — pass --archetype … to keep them`. See -[`init`](commands/init.md#choosing-the-archetypes-yourself---archetype) for the accepted values. - -To keep a single capability without changing archetypes, use [`pharn add`](commands/add.md) / -[`pharn remove`](commands/remove.md). - -Two `package.json` rules decide most surprises: - -- **A server or database package counts only under `dependencies`.** A runtime database driver - dependency (`pg`, `mysql2`, `mongodb`, `better-sqlite3`, an ORM such as `prisma` or `typeorm`) means - `backend`, like a server framework (`express`, `fastify`, `hono`, …). The same package listed only - under `devDependencies` — a mock server, a test database, tooling — does **not** add `backend`. If - your backend is bundled so that its framework is only a devDependency, pass - `pharn init --archetype backend` (with any other archetypes you want, e.g. `--archetype ssr,backend`). -- **SSR and UI frameworks count under `devDependencies` too**, because their templates list them there - (SvelteKit's `@sveltejs/kit`, React Router framework mode's `@react-router/dev`); the summary then - says `ssr ← @sveltejs/kit (package.json devDependencies)`. `peerDependencies` and - `optionalDependencies` are never read: a peer dependency names the host a plug-in library runs in, - not the project's own framework. +The summary shows what triggered each archetype (`backend ← src/app/api/`). Re-run with the ones you want, +`pharn init --archetype spa` or `--archetype ssr,backend`: it replaces detection (shown as `(not used)`) and +is recorded, so `update` keeps it. A later `init` detects again unless you pass it, and prints +`previously recorded: … — pass --archetype … to keep them` when the result differs +([details](commands/init.md#choosing-the-archetypes-yourself---archetype)). The usual surprises: a server or +database package counts only under `dependencies` (a backend bundled as a devDependency needs +`--archetype backend`), while SSR frameworks count under `devDependencies` too. Every rule is in +[Detect archetypes](commands/init.md#3-detect-archetypes); for one capability, use `pharn add` / `pharn remove`. ### Detection stopped early -The install summary says `detection stopped early: it examines at most 50,000 entries, 24 directories -deep, so these archetypes may be incomplete — pass --archetype if they are wrong` when the -file-tree scan hit one of its bounds before its result was settled. Directories it always skips -(`node_modules`, build output, framework caches, …) do not count toward the 50,000. The scan visits -names in sorted order, so a large folder that sorts early (for example 50,000 files in `public/`) can -use the budget before `src/` is reached. The result is still deterministic, but it may miss a signal: -check the archetypes the summary shows and, if they are wrong, pass them with -[`--archetype`](#detection-picked-the-wrong-archetype). The scan stops as soon as nothing more can change -its result (an `ssr` and a `backend` signal both found), so such a project is never reported as stopped -early. `pharn init --dry-run --json` reports the same thing as `"detectionTruncated": true`. +`detection stopped early: it examines at most 50,000 entries, 24 directories deep, …` (`--dry-run --json`: +`"detectionTruncated": true`) means the scan hit a bound before its result settled. It visits names in +sorted order, so a huge folder that sorts early (`public/`) can use the budget before `src/`. Check the +archetypes and pass [`--archetype`](#detection-picked-the-wrong-archetype) if they are wrong. ### Monorepos / workspaces -`pharn init` checks the **current directory** for a `.git` directory, reads the `package.json` there and runs a bounded, symlink-safe file-tree scan from it for archetype detection, then installs into that directory. The scan skips heavy or generated trees (`node_modules`, `dist`, `build`, `.next`, `out`, `coverage`, framework caches, and non-JS trees such as a Python virtualenv, or `vendor`/`target` beside the build file that owns them — a `target/` or `vendor/` folder of your own is scanned), so in a workspace it still sees `apps/` and `packages/`: a `next.config.*` directly in `apps//` or `packages//` marks a Next.js app there, and that app's `app/` route handlers and `app/api`/`pages/api` then count too (a `next.config.*` anywhere else, such as a docs site's `website/next.config.js`, does not). It does not walk up to a workspace root or read the workspace packages' own `package.json` files, so a framework that only a package's `package.json` names is not seen — pass it with [`--archetype`](#detection-picked-the-wrong-archetype). In a monorepo, run it from the directory that contains both `.git` and the app's `package.json`. Split layouts (`.git` at the root, the app's `package.json` in `apps/web/`) are unsupported in v1. +Run `pharn init` from the directory that holds both `.git` and the app's `package.json`. It does not read +the workspace packages' own `package.json` files, and split layouts (`.git` at the root, the app in +`apps/web/`) are unsupported. What it sees in `apps/` and `packages/`: [Detect archetypes](commands/init.md#3-detect-archetypes). ## Overwrite warnings -Not an error. Just before installing, `pharn init` lists which of its actual write targets already -exist in your project (capability dirs, product commands/hooks, contracts, `pharn-core`, floor -checkers, all four trusted docs, pharn's `LICENSE` copy, `pharn/features/README.md`, and -`pharn.config.json`) and asks you to confirm before overwriting. Confirm to continue -or cancel to exit cleanly (code 0); the default is **no**. - -- If **nothing** conflicts, there is no prompt at all. -- `.claude/settings.json` is never overwritten, so it never triggers the warning. -- On a re-install the list is long, so it is capped (first 10 shown, then "…and N more"). The files - `init` backs up before overwriting are listed first, marked `(edited)`, `(no pharn record)` or - `(differs from upstream)` — see [Re-running `init`](commands/init.md#6-summary) for what each - means. With a usable `pharn.records.json`, a file pharn wrote that upstream has since changed is - not marked: overwriting it loses nothing. +Not an error. Before installing, `pharn init` lists which of its write targets already exist (the paths in +[What you get](getting-started.md#what-you-get), except `pharn.records.json`) and asks; the default is **no**, +and cancelling exits 0. `.claude/settings.json` is never overwritten, so it never appears. A long list is +capped at 10, with the files `init` backs up first marked `(edited)`, `(no pharn record)` or +`(differs from upstream)` ([details](commands/init.md#6-summary)). ## Capabilities could not be fetched -Symptoms: - -- Spinner stops with "Failed to fetch PHARN" / "Failed to fetch capabilities" -- Message references `github.com/pharn-dev/pharn-oss` -- Exit code 1 - -`init` / `add` / `update` / `status` download `pharn-dev/pharn-oss` as a tarball from `codeload.github.com` (after resolving the newest verified release — or, on the `main` channel, the branch head — via `api.github.com`; see [No verified release could be resolved](#no-verified-release-could-be-resolved)) — default `status` clones too, and reads `SKILLS_VERSION` out of that clone. On the `main` channel, `update` and `status --no-drift` instead fetch the root `SKILLS_VERSION` from `raw.githubusercontent.com` without cloning; a release names its version in its tag. Check network access to all three hosts and that the repo is reachable. Note that `pharn` does not use a proxy unless you opt in with `NODE_USE_ENV_PROXY=1` — see [Proxy environment variables](#proxy-environment-variables). - -A failure to reach the host names it, and includes the underlying diagnosis rather than the runtime's -bare `fetch failed`: +Symptoms: "Failed to fetch PHARN" / "Failed to fetch capabilities", naming `github.com/pharn-dev/pharn-oss`, +exit 1. `pharn` resolves the commit via `api.github.com` and downloads it from `codeload.github.com`; on the +`main` channel, `update` and `status --no-drift` read `SKILLS_VERSION` from `raw.githubusercontent.com` +instead. Check access to all three, and note that `pharn` uses a proxy only when you +[opt in](#proxy-environment-variables). A transport failure names the host and its cause: ```text ⚠ Could not reach https://raw.githubusercontent.com/pharn-dev/pharn-oss/main/SKILLS_VERSION: @@ -370,120 +198,60 @@ bare `fetch failed`: Re-run with PHARN_DEBUG=1 for full error output. ``` -The two metadata requests (the branch-head resolve and the `SKILLS_VERSION` fetch) abort after 8 seconds; the repo download has its own, longer cap of 60 seconds. An aborted request is reported the same way. Failures that are -**not** transport failures keep their own wording — an HTTP status (`SKILLS_VERSION fetch failed -(404) from …`), an oversized body (`SKILLS_VERSION too large (… bytes)`), or an unusable value -(`SKILLS_VERSION has invalid format`) — so the message tells you which of the four happened. +Metadata requests abort after 8 seconds, the download after 60, reported the same way. Other failures say what happened: an HTTP +status (`SKILLS_VERSION fetch failed (404) from …`), an oversized body (`SKILLS_VERSION too large (… bytes)`) +or a bad value (`SKILLS_VERSION has invalid format`). ## No verified release could be resolved -Symptoms: `pharn init` without `--ref` (verified releases are the default for a new install), or -`update`, `add` or `status` on an install that follows releases (`"ref": "latest"`), stops with exit 1 -and +An install that follows releases (a new `pharn init`, or `"ref": "latest"`) stops with exit 1 and +`⚠ Could not resolve the latest verified pharn-dev/pharn-oss release: . …`, naming `--ref main`. It +installs only the newest pharn-oss **GitHub release**, never the tip of `main`. The reason: -```text -⚠ Could not resolve the latest verified pharn-dev/pharn-oss release: . This install follows - verified releases (the default for a new install, or `--ref latest`) — tags pharn-oss creates once - its post-merge CI has passed. To install the tip of main instead (the contributor channel), run - `pharn init --ref main` (or …). -``` +- **`has published no release yet (HTTP 404 …)`**: use `--ref main`, or wait. +- **`GitHub refused the request (HTTP 403 …)` / `(HTTP 429 …)`**: the unauthenticated API allows 60 requests + an hour per address, shared by your network (CI runners share one too). `pharn` takes no token: retry + later, run the step less often, or use `--ref main`, whose commit resolve degrades instead of failing. +- **`could not reach …`**: a network failure or the 8-second limit ([proxy](#proxy-environment-variables)). +- **`… is not a plain vX.Y.Z version`**, **`marked draft` / `prerelease`**: not a release `pharn` accepts. -On that channel `pharn` installs the newest pharn-oss **GitHub release**, never the tip of `main`. -It finds that release with two requests to `api.github.com`, and when either fails it stops rather than -installing something nobody verified. The reason says which: - -- **`has published no release yet (HTTP 404 …)`** — pharn-oss has not cut a release. Use `--ref main`, - or wait for one. -- **`GitHub refused the request (HTTP 403 …)` / `(HTTP 429 …)`** — the unauthenticated GitHub API allows - 60 requests an hour per address, shared by everything on your network. Wait for the limit to reset, - or use `--ref main`, whose own commit resolve degrades instead of failing. CI runners often share an - address with many other jobs, so a `pharn status --strict` step on a release install can hit this - limit there and fail; `pharn` takes no token, so the ways out are a retry, running the step less - often, or an install on `--ref main`. -- **`could not reach …`** — a network failure, or the 8-second limit. See - [Proxy environment variables](#proxy-environment-variables). -- **`the latest release's tag … is not a plain vX.Y.Z version`**, or **`marked draft` / `prerelease`** — - upstream published something pharn does not treat as a verified release. - -A release whose tree carries a different `SKILLS_VERSION` than its tag is refused as well -(`Release vX.Y.Z (…) ships SKILLS_VERSION …`): the tag and the content disagree, so neither is recorded. - -The release channel is recorded in `pharn.config.json` (`"ref": "latest"`), so `update`, `add` and -`status` keep following releases. `pharn update --ref main` switches the install to the tip of `main` -and removes the key. +A release whose tree carries another `SKILLS_VERSION` than its tag is refused too +(`Release vX.Y.Z (…) ships SKILLS_VERSION …`). `pharn update --ref main` moves an install to `main`. ## An upstream capability was skipped -Symptoms: - -- A warning naming one or more capabilities: `… could not be read and … SKIPPED — not installed` -- `init` / `add` / `update` / `status` otherwise complete normally, exit 0 - -pharn reads the newest verified release of `pharn-dev/pharn-oss` (the default) or, with `--ref main`, the -tip of `main`, so upstream can change a capability into a shape -your installed pharn version does not understand yet. Rather than abort, pharn skips that **one** -capability, names it with the reason, and carries on — it will not install content it could not -validate. - -- `update` keeps the capability's entry in `pharn.config.json` (reported as `KEPT`) but writes none - of its files, and still bumps the skills version so a later `pharn add` is not blocked. -- `status` leaves it out of the drift comparison, so `--strict` does not fail on it. -- `add` cannot install it by name — it is not in the addressable set. - -Fix: upgrade with `npm install -g @pharn-dev/pharn@latest`, or wait for upstream to finish the -change. If you no longer want the capability, `pharn remove `. +`… could not be read and … SKIPPED — not installed`, exit 0: upstream changed a capability into a shape your +`pharn` does not understand yet, so it skips that **one** and carries on. `update` keeps its entry (`KEPT`) +and writes none of its files ([details](reference/update-advanced.md#when-pharn-cannot-read-a-capability-upstream)), +`status` leaves it out of drift, and `add` cannot install it. Upgrade (`npm install -g @pharn-dev/pharn@latest`), +wait for upstream, or `pharn remove `. ## `pharn is too old for the current pharn-oss` -Symptoms: - -- `⚠ This pharn is too old for the current github.com/pharn-dev/pharn-oss: it requires -@pharn-dev/pharn vX.Y.Z or newer …` -- Exit code 1, nothing written, temporary clone cleaned up - -pharn-oss ships an optional root `MIN_CLI` file declaring the minimum CLI version its content needs. -`init` / `add` / `update` check it before doing any work. Upgrade: - -```bash -npm install -g @pharn-dev/pharn@latest +```text +⚠ This pharn is too old for the current github.com/pharn-dev/pharn-oss: it requires + @pharn-dev/pharn v0.9.0 or newer, and v0.4.0 is installed. Upgrade …, then re-run + this command. Nothing was written. ``` -A `MIN_CLI` file that is absent, unreadable, or malformed imposes **no** constraint — only a -well-formed version newer than yours refuses. +pharn-oss can ship a root `MIN_CLI` file naming the minimum CLI its content needs; `init`, `add` and +`update` refuse below it, before writing anything (exit 1). Upgrade with `npm install -g @pharn-dev/pharn@latest`. +A `MIN_CLI` that is absent, unreadable or malformed imposes no constraint. ## `pharn.config.json` was written by a newer `pharn` -Symptoms: - -- `pharn.config.json was written by pharn X.Y.Z; this is pharn A.B.C. Upgrade pharn …` on stderr -- The command carries on and its exit code is unchanged - -`pharn.config.json` records `pharnVersion`, the `pharn` that last wrote it. Your `pharn` is older than -that at major.minor, so a teammate (or CI) runs a newer one. `init`, `add`, `remove`, `update` and -`uninstall` warn and still write, `status` and the `--dry-run` previews warn too, and a `--json` report -on stdout is unchanged. An older `pharn` can undo what the newer one did: `update` and a re-run `init` -install by its older rules and stamp its own version, so the warning stops after that run, not because -anything was fixed. Upgrade, and pin one version across the team (for example as a `devDependency`): - -```bash -npm install -g @pharn-dev/pharn@latest -``` - -A patch or prerelease difference (0.20.1 against 0.20.3) never warns, nor does a missing or malformed -`pharnVersion`. See the [support policy](support-policy.md#teammates-on-different-pharn-versions). +`pharn.config.json was written by pharn X.Y.Z; this is pharn A.B.C. Upgrade pharn …` (stderr; the command +carries on, exit code and `--json` output unchanged) means a teammate or CI runs a newer `pharn` (major.minor). +An older `update` or `init` installs by its older rules and stamps its own version, so the warning stops +without anything being fixed. Upgrade, and pin one version for the team (a `devDependency`). A patch +difference or a missing or malformed `pharnVersion` never warns ([support policy](support-policy.md#teammates-on-different-pharn-versions)). ## Install failed -Symptoms: - -- Spinner stops with "Failed to install capabilities" -- Exit code 1 - -Causes include a fetch failure (network/GitHub), an archive `pharn` refused to extract (see `THREAT-MODEL.md` §2 for what the extractor rejects), or a selected capability directory missing at its expected path (`/`) in the fetched repo — the pre-flight checks the directory, and reports `Capability "" () is missing at / in the fetched repo.` (A capability whose `.md` is absent is refused earlier, during the index parse, under a different message.) Set `PHARN_DEBUG=1` and re-run for the full stack trace: - -```bash -PHARN_DEBUG=1 npx @pharn-dev/pharn init -``` +"Failed to install capabilities", exit 1: a fetch failure, an archive `pharn` refused to extract, or a +selected capability missing in the fetched repo (`Capability "" () is missing at +/ in the fetched repo.`; one whose `.md` is absent is refused earlier, at the index +parse). What the extractor rejects is in `THREAT-MODEL.md` §2. `PHARN_DEBUG=1 npx @pharn-dev/pharn init` shows the full error. ### Something in your project is in the way @@ -492,130 +260,50 @@ Refusing to install: .claude/commands/pharn-plan.md is in the way — pharn need a directory, or a directory where you have a file. Nothing was written. ``` -Before it asks to overwrite anything, `init` checks every path it is about to install, and it checks -again just before its first write. If one of them exists in your project as the wrong kind of entry -(a directory where pharn writes a file, or a file where it needs a directory), `init` stops and names -each one (up to five, then a count). That includes a **directory** named `pharn.config.json` or -`pharn.records.json`, the two files `init` writes beside the copy. Your project is left exactly as it -was — no backup directory either. Move or rename the named entries and re-run `pharn init`. This -includes `features/README.md` (or `pharn/features/README.md`): a file named `features` in your project -is in the way when the fetched pharn-oss ships that README there. - -```text -Refusing to install: pharn-review is a symbolic link inside the project, so writing through it would -put files OUTSIDE the project. Replace it with a real directory (or remove it). Nothing was written; … -``` - -A **symbolic link** on the way is refused the same way, before the overwrite prompt and before -anything is written: - -- A linked **directory** (`.claude/`, `.claude/commands`, `pharn/`, a capability directory, …): the - copy would follow it and write outside your project. Replace it with a real directory. -- A linked **file** that pharn writes (`… is a symbolic link where pharn writes a file`): the copy - would replace your link with pharn's file. Replace it with a regular file, or remove it. -- `.claude/settings.json` as a link is **fine** while it points at an existing file — `init` never - writes over an existing settings file, so a settings file kept in a dotfiles repository is left alone. - It is refused only when the link points at nothing, because `init` would then create the file in the - link's place. Create the target, or remove the link, and re-run. +`init` checks every path before it asks and again before its first write. An entry of the wrong kind (a +directory named `pharn.config.json`, or a file named `features` when pharn-oss ships +`pharn/features/README.md`) stops it, naming up to five, with nothing written: move them and re-run. A +**symbolic link** on the way is refused the same way (`… is a symbolic link inside the project, so writing +through it would put files OUTSIDE the project.`, or `… is a symbolic link where pharn writes a file`): replace +it with a real directory or file. A +`.claude/settings.json` link is fine while its target exists, since `init` never overwrites that file. ### When the `PHARN_DEBUG` hint appears -Every fatal error that came from an **exception** ends with -`Re-run with PHARN_DEBUG=1 for full error output.` — a failed clone, a failed `SKILLS_VERSION` -fetch, a copy that could not be completed. That includes an unexpected internal error: it prints -`⚠ ` and the hint, not a stack trace, and exits 1. Re-running with the variable set prints -the original error (including its `cause` and stack) instead of the hint. - -A **policy refusal** deliberately prints no hint, because there is no stack behind it: the -`MIN_CLI` refusal, the `pharn add` version / layout gates, an unknown capability name, and the -non-interactive-terminal messages all name the one action that resolves them instead. +A fatal error from an **exception** (a failed download, a copy that could not finish, an internal error) +prints `⚠ ` and `Re-run with PHARN_DEBUG=1 for full error output.` (exit 1); with the variable set +it prints the error, its `cause` and stack. A **policy refusal** (`MIN_CLI`, the `add` version gate, an +unknown capability, the no-terminal messages) has no hint: it names the action that resolves it. ## Overwrite declined -If any install targets already exist and you decline the overwrite prompt, `pharn init` cancels with exit 0 and **nothing is written into your project** (the temporary clone is cleaned up). - -Nothing is written outside your project either: the repo fetch runs first, but it downloads into a temporary directory that is removed on every path — success, cancel, and error alike. `pharn` keeps no download cache. (Earlier versions did, through `degit`; see [A leftover cache you may want to delete](#a-leftover-cache-you-may-want-to-delete) if you want to reclaim that space.) +Declining exits 0 with **nothing written**, in your project or outside it: the download goes to a temporary +directory removed on every path, and `pharn` keeps no cache. ## Proxy environment variables -**By default, `pharn` does not use an HTTP proxy.** Every network call it makes — the commit-SHA -resolve, the repo tarball, and `SKILLS_VERSION` for `update` / `status --no-drift` — goes through -Node's global `fetch`, which by default reads **no** proxy environment variable: not `https_proxy`, not -`HTTPS_PROXY`, not `no_proxy`. - -**Recent Node versions can opt in.** On Node 22.21+ and 24.5+, run `pharn` with -`NODE_USE_ENV_PROXY=1` set, or pass `--use-env-proxy` to Node (for example through `NODE_OPTIONS`). -Node's `fetch` then routes through the proxy and honours `NO_PROXY`. The details, measured on each -release line: - -- **Only `NODE_USE_ENV_PROXY=1` counts** on those versions — `true` or `0` do not. -- **The flag wins over the variable, and the last flag wins.** `--no-use-env-proxy` turns the opt-in - off even when the variable is set; the command line is read after `NODE_OPTIONS`. Either `-` or `_` - works in the flag's name. -- **Node 24.0–24.4 have no flag yet**, but there **any** non-empty `NODE_USE_ENV_PROXY` turns it on. -- **Node 20, 21, 22.0–22.20 and 23 have no opt-in at all.** - -Which variable Node reads, for the https URLs `pharn` fetches: - -- **`https_proxy`, then `HTTPS_PROXY`**, and if neither gives a proxy, **`http_proxy`, then - `HTTP_PROXY`**. Lowercase wins when both cases are set. -- **An empty `https_proxy` hides `HTTPS_PROXY`**: Node stops at the first variable that is present - at all, and then falls through to the `http_proxy` pair. -- **Only those four exact spellings are read** (on Linux and macOS). A `Https_Proxy` is never used. - On Windows, environment names are case-insensitive, so any spelling works there. - -If a proxy variable is set, `pharn` says which case applies **before** it fetches, so a network that -blocks direct egress produces an explanation rather than an unexplained timeout. Without the -opt-in, on a Node that supports it: - -```text -⚠ HTTPS_PROXY is set (http://***@proxy.internal:3128), but pharn will not use it: - its network calls go through Node's global fetch, which reads no proxy - environment variable by default. The download connects DIRECTLY, and fails - if direct egress is blocked (LIMITS.md §3a). This Node can route fetch through - the proxy — re-run with NODE_USE_ENV_PROXY=1 set. -``` - -With the opt-in on, the notice instead says the downloads go through that proxy. After a -`--no-use-env-proxy`, it names that flag as what turned the proxy off. On a Node without the opt-in, -it says so and names the Node versions that have one. - -Two details in that message are deliberate: - -- **It names the variable Node would use**, and a spelling Node never reads (`Https_Proxy`) gets its - own notice, saying it is ignored and naming the four spellings that work — rather than silence. -- **Credentials are redacted.** Any `user:password@` in the value is replaced with `***`. The value is - only printed; it is never written to `pharn.config.json`, which lives in your repository and is - committed. - -If you are behind a mandatory proxy, set `NODE_USE_ENV_PROXY=1` on a Node that supports it (above). On a -Node without it there is no workaround inside `pharn` — a named limit (`LIMITS.md` §3a), not a bug to -report. - -### This changed in the codeload release - -Earlier versions cloned through `degit`, which read `process.env.https_proxy` **itself**. If you had -set exactly that lowercase spelling, your clone _was_ proxied, and it no longer is. Your -`pharn update` and `status --no-drift` were already unproxied — those were always plain `fetch` — so -this makes one boundary consistent rather than newly broken, but it does break a setup that worked. +**By default `pharn` uses no HTTP proxy**: its calls go through Node's global `fetch`, which reads no proxy +variable unless you opt in. On Node 22.21+ and 24.5+, set `NODE_USE_ENV_PROXY=1` (only `1`) or pass +`--use-env-proxy` (for example in `NODE_OPTIONS`); `fetch` then uses the proxy and honours `NO_PROXY`. The +flag beats the variable and the last flag wins (`--no-use-env-proxy` turns it off; `-` or `_` both work). +Node 24.0–24.4 has no flag, but any non-empty `NODE_USE_ENV_PROXY` opts in. Node 20, 21, 22.0–22.20 and 23 +have no opt-in, so behind a mandatory proxy there is no workaround (a named limit, `LIMITS.md` §3a). + +Node reads `https_proxy`, then `HTTPS_PROXY`, then `http_proxy`, then `HTTP_PROXY` for `pharn`'s https URLs; +it stops at the first one present, so an empty `https_proxy` hides `HTTPS_PROXY`. Only those four spellings +count on Linux and macOS (any spelling on Windows). When one is set, `pharn` says before it fetches whether +it will use it (`⚠ HTTPS_PROXY is set (http://***@proxy.internal:3128), but pharn will not use it: …`, +naming `NODE_USE_ENV_PROXY=1` when your Node supports it, or that `--no-use-env-proxy` turned it off; with +the opt-in on, that downloads go through the proxy; on a Node without one, which versions have it). A spelling +Node never reads gets its own notice naming the four that work. Credentials are shown as `***` and never written to +`pharn.config.json`. ### A leftover cache you may want to delete -`pharn` no longer writes or reads a download cache: each fetch downloads into a fresh temp dir that is -always removed. But earlier versions cloned through `degit`, which persisted a commit-named `.tar.gz` -(~2.4 MB) plus `map.json`/`access.json` into a shared, cross-project cache directory on **every** -fetch — and **nothing ever reclaimed them**. - -That is worth stating plainly, because the directory can be much larger than "one leftover download" -suggests. `degit` does have a deletion path, but it fires only when an existing **ref's** mapped hash -changes. `pharn` passed the resolved commit SHA _as_ the ref, so every fetch wrote a self-mapped -`"": ""` entry under a **new key** — the previous hash for that key was always `undefined`, -so the delete branch could never run. One tarball accumulated per distinct upstream commit you ever -fetched, forever. A CI machine running `pharn status` on each upstream push could reach hundreds of -megabytes on an image nothing purges, and `pharn` printed nothing about it. - -Check what is there, then delete the whole directory — `pharn` will not do it for you, and nothing -reads it any more: +`pharn` keeps no download cache, but versions before the codeload download used `degit`, which kept a +~2.4 MB `.tar.gz` per upstream commit (plus `map.json`/`access.json`) in a shared cache nothing reclaims. +Nothing reads it now; check its size (`du -sh`) and delete it, or only `degit/github/pharn-dev/pharn-oss` +inside it if another tool uses `degit`: | Platform | Path | | -------- | ---------------------------------------------- | @@ -623,114 +311,27 @@ reads it any more: | Windows | `%LOCALAPPDATA%\degit` | | Other | `$XDG_CACHE_HOME/degit`, else `~/.cache/degit` | -```bash -du -sh ~/Library/Caches/degit # macOS -du -sh "${XDG_CACHE_HOME:-$HOME/.cache}/degit" # Linux and other POSIX -``` - -The directory is shared with any other tool that uses `degit`, so if you use one, delete only -`degit/github/pharn-dev/pharn-oss` inside it rather than the whole tree. - ## Another pharn process is running -`init`, `add`, `remove`, `update` and `uninstall` take a single-writer lock on the project first — -before they read `pharn.config.json` or touch the network — and hold it to their last write, across -their prompts. A second writer refuses rather than queues: - ```text ■ Another pharn process is writing to this project: pharn update (pid 4821 on my-laptop, since 2026-09-08T20:14:03.117Z). It may be waiting for input in another terminal. Wait for it to finish, or delete pharn/.lock if you are sure no pharn process is running. ``` -Exit code 1, and **nothing is read, fetched or written**. "It may be waiting for input" is always -printed: the lock does not record whether its holder sits at a prompt. Look for a `pharn` command -waiting for an answer in another terminal, and answer or cancel it (Ctrl-C releases the lock). -`--dry-run` takes no lock, so a preview runs even then. - -This exists because two concurrent runs do not merely race on a file — they corrupt the drift -baseline. Process A overwrites a file; process B, which planned against the pre-A snapshot, -overwrites it again and records its own hash; A then persists its records and config last, recording -a hash for bytes B replaced. `pharn.records.json` then disagrees with disk, and nothing in it shows -that — so `update` loses its ability to tell "pharn wrote this" from "you edited this". - -**`list` and `status` are never blocked and never take the lock**, so `pharn status --strict` stays -runnable in CI while an update is in flight. +`init`, `add`, `remove`, `update` and `uninstall` hold [the project lock](reference/project-lock.md), +`pharn/.lock`, from before they read the config to their last write, across their prompts. A second writer +refuses (exit 1, nothing read, fetched or written). Look for a `pharn` command waiting for an answer in +another terminal, and answer or cancel it (Ctrl-C releases the lock). `--dry-run`, `list` and `status` +never take the lock. ### If the lock outlives its owner -Every writing command holds the lock across its prompts, so a walked-away prompt — `init`'s summary -or overwrite question, `update`'s or `uninstall`'s confirmation, the `add` or `remove` picker — blocks -other writers in that project until it is answered or cancelled. That is deliberate (git holds its -index lock the same way): the command plans once, and what you confirm is what it writes. An edit you -make while a prompt is open is never lost: `init` backs the file up before it overwrites it, and -`update` stops before writing anything (see -[update: edits made while it waits](commands/update.md#edits-made-while-update-waits-for-your-answer)). - -An interrupted run releases the lock on its way out. That covers Ctrl-C, and a `timeout` or -`docker stop`, which arrive as `SIGINT` and `SIGTERM`. The run still exits 130 or 143 and prints -that the project may be partially updated. Three things cannot release the lock: - -- a run that is `SIGKILL`ed; -- one that loses power; -- one ended by a hangup (`SIGHUP`, a closed terminal). - -The hangup case is deliberate: listening for it would override `nohup`, and a `nohup pharn update` -would then stop mid-write. `pharn` breaks such a lock by itself when any of these hold: - -- the file is missing, unreadable, or not a well-formed lock payload — and has not been modified in - the last 10 seconds (a lock is briefly empty while its owner writes it); -- its start time is more than five minutes in the future (no running `pharn` writes that; it is - treated like a malformed payload); -- it comes from **another host** and is more than six hours old; -- it names a pid on **this** host that is no longer running; -- it comes from **this** host and started before this host last booted. - -A lock from **this** host is never broken by age: while its pid is running, `pharn` refuses, however -long ago it started (a prompt left open over lunch keeps the project). A lock from -**another host** is only retired by age — a pid means nothing across machines. If you are certain -nothing is running, deleting `pharn/.lock` is safe and is the documented escape. - -**A recycled pid keeps a dead run's lock alive until the next reboot.** "No longer running" is checked -by asking the operating system whether that pid exists. If the run that took the lock was killed and -its pid has since been reused by an unrelated process, the check finds that process and the lock reads -as live, so `pharn` keeps refusing until this host reboots (a lock started before the last boot is -broken). If the refusal names a pid that is not a `pharn` process (check with `ps -p `), delete -`pharn/.lock`. - -The boot check trusts the clock. On a machine with no battery-backed clock, or one whose clock is -corrected forward by a long way after it boots, a running `pharn` can look as if it started before -boot, and another run on the same machine may then break its lock; small corrections (under five -minutes) are tolerated. A clock set **back** by more than five minutes makes a running lock look as if -it started in the future, and it is then broken after 10 seconds like a malformed one. "This host" -means the machine's hostname: if it changes while `pharn` runs (macOS can rename itself when the -network changes), the lock is treated as one from another host — retired after six hours — and the run -cannot remove it when it finishes, so delete `pharn/.lock` yourself if no `pharn` is running. - -**A directory named `pharn/.lock`** is never a lock — `pharn` does not create one — so it is refused -with its own message rather than broken: - -```text -pharn/.lock is a directory, not a pharn lock file. pharn will not move or delete it, and cannot take the project lock while it is there. -Remove it yourself (or rename it) and re-run. -``` - -**A file named `pharn/.lock..`** is what is left when a `pharn` run is killed (`kill -9`, a -power cut) in the instant it breaks a stale lock: it moves the old lock to that name, checks it, and -deletes it. `pharn` never reads such a file and never deletes a name it did not just create, so it -stays until you delete it. It is safe to delete when no `pharn` command is running. - -**Do not run two `pharn` versions in one project at the same time.** `pharn` 0.13.0 and older lock a -different file, so neither sees the other's lock. - -**`pharn` must be a real directory.** The lock, the backups and the `pharn` layout's install all live -under `pharn/`, which a writing command creates when it is missing (and removes again if nothing ended -up in it). A `pharn` that is a symbolic link, or a regular file, is refused before anything is written: - -```text -pharn is a symbolic link. pharn keeps its lock, backups and install under pharn/ and will not write through a link that may point outside the project. -Replace it with a real directory and re-run. -``` +A run that is `SIGKILL`ed, loses power or is ended by a hangup cannot release the lock. `pharn` breaks a +stale one by itself (a dead pid on this host, a lock from before the last boot, one from another host over +six hours old, a malformed one); the rules and their residuals, and the stray `pharn/.lock` directory or +`pharn/.lock..` file, are in [If the lock outlives its owner](reference/project-lock.md#if-the-lock-outlives-its-owner). +If you are certain no `pharn` is running, deleting `pharn/.lock` is safe. ## `add` / `update` say to run init first @@ -738,29 +339,18 @@ Replace it with a real directory and re-run. No pharn.config.json found. Run `pharn init` first. ``` -All non-`init` commands operate on an already-installed project. Run `pharn init` to create `pharn.config.json`. - -This message means the file is **not there**, or is there but cannot be read as a config at all: it -is not a regular file (a directory, a FIFO), it cannot be opened or is larger than 16 MiB, its JSON -is not an object, it has no string `skillsVersion`, or it has neither a `capabilities` nor a `modules` -key. Invalid JSON, and a config that has those keys but an invalid field, get their own named -errors instead — see [the corrupt-config case](#a-command-rejects-an-invalid-config-does-not-say-run-init) -below. - -If the file **is** there, look at it before you run `pharn init`: init **overwrites** the config, so -re-running it can cost you your recorded capabilities and manual `pharn add` provenance. A re-run -`init` over such a file says so in its summary — `the previous pharn.config.json could not be read -(); nothing is carried over, so manual capabilities will be dropped` — and its overwrite -prompt defaults to No. Move the file aside (`mv pharn.config.json pharn.config.json.bak`) if you want -to keep a copy. +The file is **not there**, or cannot be read as a config at all (not a regular file, unopenable or over +16 MiB, not a JSON object, no string `skillsVersion`, neither `capabilities` nor `modules`). Invalid JSON and +invalid fields get [their own errors](#a-command-rejects-an-invalid-config-does-not-say-run-init). If the +file **is** there, look at it first: `init` **overwrites** it, dropping your recorded capabilities and manual +`pharn add` provenance (its summary says `the previous pharn.config.json could not be read (); …` +and its prompt defaults to No). Keep a copy with `mv pharn.config.json pharn.config.json.bak`. ### Legacy (pre-archetype) config -```text -This project uses the legacy module layout (pre-archetype), which is no longer supported. Re-run `pharn init` to reinstall with the archetype/capability model. -``` - -If your `pharn.config.json` predates the archetype model (it has `modules` but no `capabilities`), the module/manifest install path it relied on has been removed (live pharn-oss ships no `manifest.json`). Re-run `pharn init` to reinstall using archetype detection. +``This project uses the legacy module layout (pre-archetype), which is no longer supported. Re-run `pharn init` …`` +means a config with `modules` but no `capabilities`: re-run `pharn init`. A config at the removed `flat` +layout gets [its own message](reference/update-advanced.md#an-install-recorded-at-the-flat-layout). ## A command rejects an invalid config (does NOT say "run init") @@ -768,120 +358,42 @@ If your `pharn.config.json` predates the archetype model (it has `modules` but n pharn.config.json: capabilities[1].source must be "auto" or "manual" (found "guess"). Fix it by hand, or delete the field — an absent `source` is valid and the next `pharn update` will set it. ``` -If `pharn.config.json` **exists but was hand-edited into an invalid state**, `add` / `status` / -`update` / `remove` / `list` print the loud, specific error above (naming the offending field) and -exit non-zero — they do **not** say to run `pharn init` (the file is there; re-running init would -offer to clobber your edits). Fix the named field and re-run. The same refusal covers a `capabilities` -that is not an array or has an invalid entry, an `archetypes` that is not a list of known archetypes, -and a `skillsVersion` or `commit` that is not a version / a full commit SHA (or `null`) — see -[`pharn.config.json`](reference/pharn-config.md#skillsversion-and-commit--checked-when-the-config-loads). - -The `models` block is **not** checked here: it is pharn-oss's, and no command refuses to run over it. -See [`pharn status` lists a problem with `models`](#pharn-status-lists-a-problem-with-models). Nor is -the `seam` block: it is pharn-oss's too, `pharn` carries it unchanged, and pharn-oss's own floor -checks it (releases up to 0.19.0 refused, in every command, a `seam` block pharn-oss accepts — one -with an extra key or a repeated step; upgrade `pharn` if one stops yours). +A hand-edited invalid field (`capabilities` not an array or with a bad entry, unknown `archetypes`, a +`skillsVersion` or `commit` that is not a version / full SHA / `null`) makes `add`, `status`, `update`, +`remove` and `list` name it and exit 1 ([fields](reference/pharn-config.md#skillsversion-and-commit--checked-when-the-config-loads)). +Fix it by hand. The `models` and `seam` blocks are pharn-oss's and never refused +([`models`](#pharn-status-lists-a-problem-with-models)). ### The config is not valid JSON -```text -/path/to/your/project/pharn.config.json is not valid JSON (line 4, column 1). The file exists — fix its syntax by hand. Do NOT run `pharn init` to clear it: init OVERWRITES this config, discarding your recorded capabilities, any manual `pharn add` provenance, and a hand-edited models block. If it is beyond repair, move it aside first (`mv pharn.config.json pharn.config.json.bak`), then run `pharn init`. -``` - -A syntax error — most often a trailing comma — is reported with the file's full path and, when the -JSON parser supplies one, the **line and column** of the offending byte. Open the file at that -position and fix it; nothing else is needed, and nothing has been written. - -**Do not reach for `pharn init` here.** It rewrites `pharn.config.json` wholesale: a hand-edited -`models` block becomes pharn-oss's again, keys of your own such as `testResults` and the `seam` -block are not carried over (nothing is, from a file that does not parse), and every capability is re-stamped `source: "auto"`, which discards the record of which -capabilities you added by hand with `pharn add`. That record -lives nowhere else, and `pharn update` reads it to keep your manual additions across upgrades. - -If the file is genuinely beyond repair, move it out of the way first so you can still read it, then -re-install: - -```bash -mv pharn.config.json pharn.config.json.bak -pharn init -``` - -You can then copy your `models` / `seam` blocks back out of the `.bak` file, and re-add anything you -had installed manually with `pharn add `. - -Two neighbouring cases are deliberately **not** reported this way, because the file is not readable -in the first place: a config that is **absent**, or one that exists but cannot be read at all (a -permissions problem, a directory, a FIFO or a device sitting at that path, or a file over 16 MiB), -still says -[`No pharn.config.json found`](#add--update-say-to-run-init-first). +``… pharn.config.json is not valid JSON (line 4, column 1). The file exists — fix its syntax by hand. Do NOT run `pharn init` …`` +names the line and column (most often a trailing comma). Fix it there. **Do not reach for `pharn init`**: it +rewrites the file (your `models` edits, `testResults` and `seam` are lost, and every capability becomes +`source: "auto"`, losing which ones you added by hand). Beyond repair? `mv pharn.config.json pharn.config.json.bak`, +run `pharn init`, copy your `models` / `seam` blocks back, and re-add manual capabilities with `pharn add`. ## `pharn status` lists a problem with `models` -```text -pharn-oss's rules reject this block: - stage "plan" model "gpt-4" is not an alias {sonnet, opus, haiku, fable, inherit} nor a claude-* id -``` - -The `models` block in `pharn.config.json` is pharn-oss's (see -[Models](reference/pharn-config.md#models)), so no `pharn` command refuses to run over it. `status` -lists what pharn-oss's rules reject, and you fix it by hand. The checker installed with PHARN says the -same: `node pharn/floor/check-model-config.mjs validate`. - -- **A block in the format pharn wrote before 0.7.0** (a top-level `default`, ids such as `opus-4-8`) - — `pharn` no longer converts it, and `pharn update` keeps it as yours. Replace it by hand, or delete - the `models` key from `pharn.config.json` so the next `pharn update` writes pharn-oss's. -- **A stage, alias or effort pharn-oss added after your `pharn` was released** — upgrade `pharn`: the - copy of pharn-oss's rules it checks with predates the change. -- **Your values differ from the installed commands' frontmatter** — not an error here. - `node pharn/floor/check-model-config.mjs agreement` lists each difference; nothing runs it - automatically. The two have different reach: `/pharn-ship` and `/pharn-loop` read the block to pick - the **model** they request for the stages they route (never the effort), while a `/pharn-` - you run directly uses its own frontmatter. Editing only the block causes no file drift. Editing a - command's frontmatter makes that file `modified`, so `pharn update` skips it and withholds the - skills-version bump until you restore it or run `pharn update --force` (which backs it up first). - -`pharn update` lists the same problems when it keeps your block, and `pharn init` names them when -pharn-oss's own block fails — it writes none then. +`pharn-oss's rules reject this block:` followed by the reasons. The block is pharn-oss's +([Models](reference/pharn-config.md#models)), so nothing refuses over it; fix it by hand +(`node pharn/floor/check-model-config.mjs validate` says the same). An old-format block (a top-level +`default`, ids such as `opus-4-8`) is kept by `update`: replace it, or delete the `models` key so the next +`update` writes pharn-oss's. A stage, alias or effort newer than your `pharn` needs an upgrade. Values that +differ from the commands' frontmatter are not an error (`… check-model-config.mjs agreement` lists them): +`/pharn-ship` and `/pharn-loop` read the block's **model** for the stages they route, a `/pharn-` run +directly uses its frontmatter, and editing that frontmatter makes the file `modified` +([details](reference/update-advanced.md#the-models-block)). ## Unknown command -```text -Unknown command: ... -``` - -Run `pharn --help`. Valid commands: `init`, `add`, `remove` (alias `rm`), `update`, `list`, `status`, -`uninstall`. `pharn --help` shows one command and only the options it takes. +`Unknown command: ...`: the commands are `init`, `add`, `remove` (alias `rm`), `update`, `list`, `status` +and `uninstall`. `pharn --help` shows one command and the options it takes. ## Unknown option, or an unexpected argument -```text -Unknown option: "--sctrict" -Run `pharn --help` for usage. -``` - -```text -Unexpected argument: "extra" -Run `pharn --help` for usage. -``` - -`pharn` refuses argv it does not understand rather than ignoring it, and refuses **before** running -any command — so nothing is fetched and nothing is written. Both messages go to stderr as one -line plus a pointer at `pharn --help` — not the whole usage text, which used to scroll the error -away — and exit **1**. - -This matters most in CI: a mistyped `pharn status --sctrict` used to run in the default exit-0 mode, -so the drift gate was silently disarmed while every run stayed green. `pharn update --froce` used to -run un-forced, and `pharn add a11y extra` used to drop the third argument. - -Two consequences worth knowing: - -- A genuine `--help` or `--version` does **not** excuse a bad sibling — neither an unrecognised one - nor one this command does not take: `pharn --help --bogus` and `pharn status --help --force` both - refuse instead of printing the usage text. `pharn status --help` on its own is unaffected. -- Options are **scoped to one command**, and passing one to a different command is an error, not a - no-op — see the next section. - -Run `pharn --help` for the full option list, or `pharn --help` for one command's options. +`Unknown option: "--sctrict"` or `Unexpected argument: "extra"`, then ``Run `pharn --help` for usage.``, exit +**1**, before any command runs, so nothing is fetched or written (a mistyped `--strict` in CI fails instead of +running unarmed). A `--help` or `--version` does not excuse a bad sibling: `pharn --help --bogus` refuses. ## Unsupported option for this command @@ -890,8 +402,8 @@ Unsupported option for `status`: "--force" Run `pharn --help` for usage. ``` -Each option is taken by the commands listed below (`--json`, `--yes`, `--ref` and `--dry-run` by -several), and `pharn` refuses the ones a command does not take: +An option the command does not take exits **1** like an unknown one (labelled differently, so you do not +hunt for a typo): | command | options it accepts | | --------------- | --------------------------------------------------------------------------------------------------------------- | @@ -904,69 +416,33 @@ several), and `pharn` refuses the ones a command does not take: | `uninstall` | `--yes` / `-y` | | _any_ | `--help` / `-h`, `--version` / `-v` | -The message goes to stderr with the `pharn --help` pointer and exits **1**, exactly like `Unknown option` — the -label differs only because the option is one `pharn` _knows_, so "unknown" would send you hunting for -a typo that is not there. - -Before this, such an option was parsed and silently dropped. That was worst in CI: `pharn update ---json | jq` received human-readable output and a **success** exit code, and -`pharn list --strict` exited 0 no matter what it found (`status --json` is now a real option — see -[`pharn status`](commands/status.md#json-output) — and so is `update --json`, which implies `--dry-run`). With no command word at all, -`pharn --force` and `pharn --strict` each ran a **full `init`** while ignoring the option. - -Two options imply another, so neither needs a partner. `--json` on `update` or `init` implies `--dry-run`: -`pharn update --json` is `pharn update --dry-run --json`, and `pharn init --json` — or a bare `pharn --json`, -since `init` is the default command — is `pharn init --dry-run --json`. `pharn update --compact` implies -`--json`, and so `--dry-run`. See [`pharn update`](commands/update.md#json-output) and -[`pharn init`](commands/init.md#json-output). - -Option **values** are checked too. An on/off option takes no value, so `pharn list --json=false` is refused -with `Option takes no value: "--json=false"` rather than read as anything — pass the bare `--json`, or leave -it out. `--ref` and `--archetype` may each be given once (`Repeated option: "--ref"`), and only `--no-drift` -is a negated option: `--no-dry-run`, `--no-yes` and `--no-ref` are `Unknown option`. +`init` is the default command, so a bare `pharn --json` is `pharn init --dry-run --json`. An on/off option +takes no value (`Option takes no value: "--json=false"`), `--ref` and `--archetype` may each be given once +(`Repeated option: "--ref"`), and `--no-drift` is the only negated option (`--no-dry-run`, `--no-yes` and `--no-ref` are `Unknown option`). ## Removing PHARN by hand -[`pharn uninstall`](commands/uninstall.md) removes PHARN for you whenever `pharn.records.json` is usable. -When it refuses because the store is missing or corrupt, nothing can be proven to be `pharn`'s, so the removal is yours to do. The steps below remove what an install -writes; **review each path before deleting it** — anything you wrote yourself is yours to keep. - -1. **Find what the install added.** If you committed the install, `git log --diff-filter=A -- pharn.config.json` - names the commit, and `git show --stat ` lists every file it added. `git diff -- ` - shows whether you changed one since. -2. **Delete the installed surfaces** (paths for the `pharn` layout; an install made by `pharn` 0.20.x or - older at the legacy `flat` layout keeps the same names at the project root — `pharn-review/`, - `pharn-pipeline/`, `pharn-contracts/`, `.dev/floor/`, `features/README.md`, `PHARN-LICENSE`, and the - four trusted docs): - - `pharn/pharn-pipeline/`, `pharn/pharn-review/`, `pharn/pharn-contracts/`, `pharn/pharn-core/`, - `pharn/floor/` - - `pharn/CONSTITUTION.md`, `pharn/ARCHITECTURE.md`, `pharn/THREAT-MODEL.md`, `pharn/LIMITS.md` - (an install from pharn-oss older than 7.0.0 has these two at the project root instead), - `pharn/LICENSE`, `pharn/features/README.md` — but **not** your own `pharn/features//` - folders, and not `pharn/memory-bank/` or `pharn/spec-template.md`, which are your data - - the `pharn-*.md` files in `.claude/commands/` (not `pharn-dev-*`, and none of your own commands) - - the hook scripts PHARN installed in `.claude/hooks/` -3. **Unwire the hooks.** Remove the entries in `.claude/settings.json` (and `.claude/settings.local.json`) - whose command runs one of the scripts you deleted. If `pharn init` created `settings.json` and you never - added anything to it, you can delete the file. (`pharn uninstall` does this itself when - `pharn.records.json` has a `.claude/settings.json` entry — a fresh `init` records one.) -4. **Delete pharn's own files:** `pharn.config.json`, `pharn.records.json`, and `pharn/.lock` if it - exists and no `pharn` command is running. `pharn/.run/` (or `.pharn/` before pharn-oss 7.0.0) is - runtime scratch written while PHARN commands run, and `pharn/.backup/` holds backups `pharn` made — - delete them once you no longer need them. +[`pharn uninstall`](commands/uninstall.md) removes PHARN whenever `pharn.records.json` is usable. Without +one, nothing can be proven to be `pharn`'s, so **review each path before deleting it**: + +1. **Find what the install added**: `git log --diff-filter=A -- pharn.config.json`, then + `git show --stat `; `git diff -- ` shows whether you changed a file since. +2. **Delete the installed surfaces** in [What you get](getting-started.md#what-you-get) (the `pharn-*.md` + commands only, not `pharn-dev-*` or your own; the hooks and agents PHARN installed). Keep your + `pharn/features//` folders, `pharn/memory-bank/` and `pharn/spec-template.md`. A pharn-oss older + than 7.0.0 left `THREAT-MODEL.md` and `LIMITS.md` at the root; a former `flat` install the same surfaces + at the root (`.dev/floor/`, `features/README.md`, `PHARN-LICENSE`). +3. **Unwire the hooks** in `.claude/settings.json` (and `.claude/settings.local.json`) that run a deleted + script; delete `settings.json` if `pharn init` created it and you never added to it. +4. **Delete** `pharn.config.json`, `pharn.records.json`, `pharn/.lock` (no `pharn` running), and, when you no + longer need them, `pharn/.run/` (`.pharn/` before pharn-oss 7.0.0) and `pharn/.backup/`. ## Local development issues -| Problem | Fix | -| ----------------------------------- | ----------------------------------------------- | -| `pharn` not found after editing CLI | `npm run build:install-local` from `pharn-cli/` | -| Type errors in tests | `npm run typecheck` | -| Stale dist | `npm run build` | - -See [Contributing](../CONTRIBUTING.md). +`pharn` not found after editing the CLI: `npm run build:install-local`. Type errors in tests: +`npm run typecheck`. Stale dist: `npm run build`. See [Contributing](../CONTRIBUTING.md). ## Related -- [Getting started](getting-started.md) -- [init command](commands/init.md) -- [pharn.config.json](reference/pharn-config.md) +[Getting started](getting-started.md) · [init](commands/init.md) · [update](commands/update.md) · +[update: less common situations](reference/update-advanced.md) · [The project lock](reference/project-lock.md) · [pharn.config.json](reference/pharn-config.md)