From dc204eb36e8b508072016ccd65198d7ae2ccd9bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 13:14:17 +0100 Subject: [PATCH 1/2] docs: README and command pages use current paths and facts (C4.1, CORE-174) Bring the README and command pages in line with the code and pharn-oss 7.x: the write guard's pharn/.run/ paths, pharn/spec-template.md, pharn/memory-bank/, the root footprint left in place now that the migration is gone, init's one "Ready to install?" question, init --yes, the newest verified release as the default source, the legacy-source inference, no permanent exclusion (a Planned roadmap row), a quick start that does not fail after create-next-app's own commit, and example config/records blocks regenerated from a real pharn 0.20.0 run. `pharn --help` no longer says each option belongs to ONE command. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 ++ README.md | 49 ++++++++++++++++++--------------- docs/commands/add.md | 7 +++-- docs/commands/init.md | 15 ++++++---- docs/commands/list.md | 5 ++-- docs/commands/remove.md | 8 ++++-- docs/commands/update.md | 6 ++-- docs/getting-started.md | 8 ++++-- docs/reference/pharn-config.md | 34 ++++++++++++++++------- docs/reference/pharn-records.md | 16 +++++++---- docs/roadmap.md | 1 + docs/troubleshooting.md | 8 ++++-- src/lib/cli-args.ts | 2 +- tests/cli-args.test.ts | 4 +++ 14 files changed, 107 insertions(+), 58 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index caf919b8..aa5dcf6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ Releases 0.4.0 and older are in [CHANGELOG-ARCHIVE.md](CHANGELOG-ARCHIVE.md). ### Changed +- **`pharn --help` no longer says each option belongs to one command.** `--json`, `--yes`, `--ref` and `--dry-run` are taken by several, as the lines below the header already showed. The header now reads "Options (each names the commands that take it; any other command refuses it):". + - **New configs no longer carry `modules`; pharn 0.20.0 is the oldest CLI that can read them.** `pharn init` wrote `"modules": []` into every archetype `pharn.config.json` only because `pharn` 0.3.0 to 0.19.x reads a config without a `modules` array as no config at all. It no longer does, and every write (`init`, `add`, `remove`, `update`) now also drops the fields only older CLIs wrote (`modules`, `constitution`, `installedSkills`, `stackAnswers`, `isMultiTenant`) when it finds them. A config that still carries them loads in every command as before. If a teammate runs `pharn` 0.19.x or older, upgrade it first: it reports _"No pharn.config.json found"_ for a config 0.21.0 wrote, and running `pharn init` there would replace the file. ### Removed diff --git a/README.md b/README.md index 752faab1..338250bd 100644 --- a/README.md +++ b/README.md @@ -86,14 +86,15 @@ Run PHARN inside an existing git project: npx @pharn-dev/pharn@latest init ``` -For a new app, initialize git before installing PHARN: +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: ```bash npx create-next-app@latest my-app cd my-app -git init -git add -A -git commit -m "init" +[ -d .git ] || { git init && git add -A && git commit -m "init"; } npx @pharn-dev/pharn@latest init ``` @@ -179,17 +180,20 @@ 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. When your -`.gitignore` still names the old `.pharn/`, `pharn update` prints the -replacement line; it never rewrites yours. +`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: the first `pharn update` to -7.0.0 or later deletes the two docs if you never edited them. It never moves the -other two (nothing proves they are PHARN's); it prints the `git mv` command, or -says to merge by hand when the `pharn/` copy already exists — see +`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). **Two version numbers, on purpose.** The npm package `@pharn-dev/pharn` carries @@ -215,18 +219,19 @@ 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/**` — applies **only while** `/pharn-ship`, `/pharn-loop`, or -`/pharn-review` has an open marker (`.pharn///active.json`; ship -and review via `pharn/floor/run-marker.mjs`, loop via +`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/**`, `.claude/**`, -`pharn.config.json`, and `.pharn/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. +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/writes-scope.json`) +(`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. @@ -280,7 +285,7 @@ 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` in the project root. The write guard denies Claude +`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). @@ -289,7 +294,7 @@ 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 `memory-bank/` through a gated provenance check. | +| `/pharn-memory-promote` | Promote one lesson into `pharn/memory-bank/` through a gated provenance check. | ## CLI commands @@ -377,7 +382,7 @@ PHARN is intentionally conservative about writes: - `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`, `memory-bank/`, or your detected + 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 diff --git a/docs/commands/add.md b/docs/commands/add.md index 1c5e2295..eb6c8f77 100644 --- a/docs/commands/add.md +++ b/docs/commands/add.md @@ -52,7 +52,7 @@ A `MIN_CLI` that is missing, unreadable, or malformed imposes **no** constraint ## Skipped upstream capabilities -`add` clones the tip of upstream `main` (or the newest release, for an install that follows releases), so a +`add` clones the newest verified release (or the tip of upstream `main`, for an install made with `--ref main`), so a capability can exist upstream in a shape your installed pharn version cannot read yet. `add` names each one and continues: ```text @@ -66,8 +66,9 @@ Upgrade pharn, or wait for upstream to finish the change. ## Version mismatch -`add` clones what your install follows — the tip of `pharn-dev/pharn-oss` `main`, or the newest -verified release for a config that records `"ref": "latest"` (`add` has no `--ref` of its own) — so the clone +`add` clones what your install follows — the newest verified release for a config that records +`"ref": "latest"` (what `init` records by default), or the tip of `pharn-dev/pharn-oss` `main` for one +that records no `ref` (an install made with `--ref main`; `add` has no `--ref` of its own) — so the clone can be **newer** than what you installed. Copying one capability from that clone and recording the clone's version would claim your whole install had moved to it, when every other file still holds the old version's bytes — and [`pharn status`](status.md) would then call a stale install current. diff --git a/docs/commands/init.md b/docs/commands/init.md index b306d1ce..4e69d3cf 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -1,6 +1,6 @@ # pharn init -Interactive setup wizard — or, with `--dry-run`, a preview, and with `--yes`, a prompt-free install into a fresh project. Default command when you run `pharn` with no subcommand. +Interactive install (a summary, then "Ready to install?") — or, with `--dry-run`, a preview, and with `--yes`, a prompt-free install into a fresh project. Default command when you run `pharn` with no subcommand. ```bash pharn init @@ -72,8 +72,12 @@ previews the install for those archetypes (the same summary block, then the plan ## `init` is interactive by default -`init` asks which capabilities to install, and — only when any of its write targets already exist — -whether to overwrite them, so a plain `pharn init` needs a terminal. Off a TTY (CI, a pipe, a script) it +`init` prints a summary of the archetypes it detected and the capabilities they select, then asks +**Ready to install?**, and — only when any of its write targets already exist — whether to overwrite +them, so a plain `pharn init` needs a terminal. It does not ask which capabilities to install: the +selection follows your archetypes, and you change it with +[`--archetype`](#choosing-the-archetypes-yourself---archetype) or, after the install, with +[`pharn add`](add.md) and [`pharn remove`](remove.md). Off a TTY (CI, a pipe, a script) it **exits 1** instead of prompting into a stream nobody is reading: ```console @@ -326,7 +330,8 @@ sequenceDiagram ## When pharn cannot read a capability upstream -`init` fetches `pharn-dev/pharn-oss` at `main`, so a capability can be in a shape your installed +`init` fetches the newest verified release of `pharn-dev/pharn-oss` (or the tip of `main` with +`--ref main`), so a capability can be in a shape your installed pharn version does not understand yet. `init` **skips that one capability and names it**, before the summary you act on, then installs everything else normally: @@ -591,7 +596,7 @@ overwrites them. The install also copies pharn-oss's Apache-2.0 `LICENSE` — to `pharn/LICENSE`. The destination is deliberately **not** a plain root `LICENSE`: that file is yours, and pharn never overwrites it. The copy exists so that a repo you commit and -publish carries the license grant for the ~450 Apache-2.0 files pharn put in it. +publish carries the license grant for the several hundred Apache-2.0 files pharn put in it. The four trusted docs land in `pharn/` (`pharn/CONSTITUTION.md`, `pharn/ARCHITECTURE.md`, `pharn/THREAT-MODEL.md`, `pharn/LIMITS.md`), where pharn-oss keeps them from 7.0.0 on. A root diff --git a/docs/commands/list.md b/docs/commands/list.md index bbda0ddd..2ef81efa 100644 --- a/docs/commands/list.md +++ b/docs/commands/list.md @@ -51,8 +51,9 @@ Capabilities are grouped by role with a per-role count, one capability per line: A capability you installed by hand with [`pharn add`](add.md) is marked `(manual)` — it is preserved across [`pharn update`](update.md) rather than re-derived from your archetypes, unless upstream has removed the capability from the index (then `update` drops the entry and reports it). Automatically-selected -capabilities, and entries written before the field existed, render unmarked; those legacy entries are -inferred as manual on the next `update` and follow the same preserve-or-drop rule. See +capabilities, and entries written before the field existed, render unmarked. The next `update` infers +a legacy entry's source: one your archetypes still select becomes `auto`; one they do not select becomes +`manual` and follows the same preserve-or-drop rule. See [`capabilities[].source`](../reference/pharn-config.md#capabilitiessource--selection-provenance). Nothing is ever written, fetched, or cloned — and `list` never takes the project lock, so it is safe to diff --git a/docs/commands/remove.md b/docs/commands/remove.md index 8ca4cfce..e5921a73 100644 --- a/docs/commands/remove.md +++ b/docs/commands/remove.md @@ -30,7 +30,7 @@ pharn remove # no arg, in a terminal: interactive multi-select p store never describes files that are gone. Removal needs **no network and no clone** — everything is derivable from `capabilities` plus your -filesystem. `CONSTITUTION.md`, `memory-bank/`, and your detected `archetypes` are **never** touched. +filesystem. `CONSTITUTION.md`, `pharn/memory-bank/`, and your detected `archetypes` are **never** touched. ## The capability argument @@ -139,8 +139,10 @@ guarantee. _resolved_ half is unaffected. If your archetypes still select that capability — and most capabilities are `universal`, so they usually do — the next `update` may re-add it as `auto` and name it under `ADDED`. `remove` cannot warn about this: it has no capability index and never fetches one, so it -cannot know whether your archetypes select the thing you are removing. To keep a capability out for -good, remove the archetype that selects it. +cannot know whether your archetypes select the thing you are removing. There is no permanent +exclusion today ([planned](../roadmap.md#planned)): a `universal` capability is selected whatever your +archetypes are, so `update` re-adds it. Only a re-run `pharn init --archetype ` changes the +recorded `archetypes`, which drops a capability that only the archetypes you leave out select. The warning is derived from the stored field alone, so `remove` stays offline. An entry whose `source` is **absent** (a config predating the field) warns nothing — its provenance is genuinely unknown until diff --git a/docs/commands/update.md b/docs/commands/update.md index 2e63f067..66ce6a0c 100644 --- a/docs/commands/update.md +++ b/docs/commands/update.md @@ -389,7 +389,8 @@ drops the same way, after listing them in its overwrite prompt. ## When pharn cannot read a capability upstream -pharn always fetches `pharn-dev/pharn-oss` at `main`, so a capability can change upstream in a way +`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: @@ -767,7 +768,8 @@ exits 0. Use [`pharn status --strict`](status.md) when you want CI to fail on dr `--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`](init.md) has no `--yes` and is interactive-only — see its note for why. +> [`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. ## Before you confirm diff --git a/docs/getting-started.md b/docs/getting-started.md index a4be737a..82a99713 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -43,10 +43,14 @@ npx @pharn-dev/pharn init npx create-next-app@latest my-app cd my-app npx shadcn@latest init -git init && git add -A && git commit -m "init" +[ -d .git ] || { git init && git add -A && git commit -m "init"; } npx @pharn-dev/pharn init ``` +`create-next-app` already runs `git init` and makes the first commit (unless git is missing or you pass +`--disable-git`), so the git line runs only when `.git` is absent. `pharn init` needs a git repository at +the project root. + `pharn` with no subcommand runs `init` (same as `pharn init`). ## The install flow @@ -127,7 +131,7 @@ The pipeline is eight typed stages: `/pharn-spec → /pharn-plan → /pharn-gril **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 `memory-bank/` through a gated provenance check. +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. ## Next steps diff --git a/docs/reference/pharn-config.md b/docs/reference/pharn-config.md index bbfe8176..471a6c9e 100644 --- a/docs/reference/pharn-config.md +++ b/docs/reference/pharn-config.md @@ -146,21 +146,33 @@ from the list. A value that is not a list of ## Example +Written by `pharn` 0.20.0 from pharn-oss v7.22.0, in a project whose `package.json` has no +dependencies (so the archetype is `lib`): `pharn init --yes`, then `pharn add n-plus-one`. The +`models` stages and most capabilities are trimmed to `…`; the key order is the one `pharn` writes. + ```json { - "pharnVersion": "0.4.0", - "skillsVersion": "3.0.2", + "pharnVersion": "0.20.0", + "skillsVersion": "7.22.0", "repo": "pharn-dev/pharn-oss", - "commit": "daa06788…", - "installedAt": "2026-06-11T00:00:00.000Z", - "archetypes": ["ssr", "backend"], + "commit": "9422b97f9bcef022d240822024e75a1a49c6e278", + "ref": "latest", + "installedAt": "2026-11-17T12:07:43.364Z", + "models": { + "stages": { + "default": { "model": "sonnet", "effort": "high" }, + "spec": { "model": "opus", "effort": "high" }, + "…": "…" + } + }, + "archetypes": ["lib"], "capabilities": [ - { "name": "a11y", "role": "griller", "source": "auto" }, - { "name": "security", "role": "griller", "source": "auto" }, + { "name": "architecture", "role": "griller", "source": "auto" }, + { "name": "…", "role": "…", "source": "auto" }, + { "name": "trust-fence", "role": "lens", "source": "auto" }, { "name": "n-plus-one", "role": "lens", "source": "manual" } ], - "layout": "pharn", - "models": { "stages": { "…": "…" } } + "layout": "pharn" } ``` @@ -419,7 +431,9 @@ That value is read from your local config only — never fetched — and if the does not carry a plain version string, the clause is omitted and the prompt is otherwise unchanged. `init` reaches that prompt only in an interactive terminal: off a TTY it exits **1** before fetching -anything, and it deliberately has no `--yes`. +anything. `init --yes` never answers it: it skips only the "Ready to install?" question, and with any +conflicting path it exits **1** having written nothing (an existing `pharn.config.json` refuses before +the download) — see [`--yes`](../commands/init.md#install-without-prompts---yes). For the files PHARN installs (as opposed to this config), `update` never overwrites one you have edited unless you pass `--force` — see the [update decision table](../commands/update.md#the-decision-table). diff --git a/docs/reference/pharn-records.md b/docs/reference/pharn-records.md index c956f3c5..512d65bf 100644 --- a/docs/reference/pharn-records.md +++ b/docs/reference/pharn-records.md @@ -18,15 +18,21 @@ missing ones; files identical to upstream are no-ops and have their records refr ## Shape +Five of the 546 entries the store held after the run that wrote the +[`pharn.config.json` example](pharn-config.md#example) (`pharn init --yes`, then `pharn add n-plus-one`, +`pharn` 0.20.0, pharn-oss v7.22.0), hashes shortened to `…`. Keys are sorted. + ```json { "schemaVersion": 1, - "skillsVersion": "3.0.2", - "commit": "daa06788…", + "skillsVersion": "7.22.0", + "commit": "9422b97f9bcef022d240822024e75a1a49c6e278", "files": { - "pharn/CONSTITUTION.md": "e3b0c44298fc1c149afbf4c8996fb924…", - ".claude/hooks/set-writes-scope.cjs": "9f86d081884c7d659a2feaa0c55ad015…", - "pharn/pharn-review/n-plus-one/n-plus-one.md": "2c26b46b68ffc68ff99b453c1d304134…" + ".claude/hooks/set-writes-scope.cjs": "668a9b0154c341a98a9f73a1ab0fe98e…", + ".claude/settings.json": "d218f551515df41482b8a18885b76ee8…", + "pharn.config.json#/models": "da4baeb9b1ed1c7e0f06bfd6b4f79dcf…", + "pharn/CONSTITUTION.md": "8f0c7cad7d2c7350da2bcb1674509f2a…", + "pharn/pharn-review/n-plus-one/n-plus-one.md": "5149e3524a2aa5c78407787c41341b84…" } } ``` diff --git a/docs/roadmap.md b/docs/roadmap.md index 43122f5f..5bad8fcd 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -38,6 +38,7 @@ What the latest release does; the [CHANGELOG](../CHANGELOG.md) says which versio | Framework-specific capabilities | Beyond today's universal + archetype-triggered set | | Stack scaffolding | Install npm packages / generate app code for a detected framework | | Migration for existing projects | Onboard repos with significant git history (today the CLI only requires a `.git` directory and hard-fails without one; it never inspects history and issues no warning) | +| Permanent capability exclusion | Keep a removed capability out of every later `update`, `universal` ones included (today `update` re-adds whatever your archetypes select) | | Other agents | Codex and Cursor in addition to Claude Code | ## Related diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 35706829..27770623 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -419,7 +419,8 @@ 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 always reads `pharn-dev/pharn-oss` at `main`, so upstream can change a capability into a shape +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. @@ -531,7 +532,7 @@ non-interactive-terminal messages all name the one action that resolves them ins ## Overwrite declined -If any install targets already exist and you decline the overwrite prompt, the wizard cancels with exit 0 and **nothing is written into your project** (the temporary clone is cleaned up). +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.) @@ -889,7 +890,8 @@ Unsupported option for `status`: "--force" Run `pharn --help` for usage. ``` -Every option belongs to exactly one command, and `pharn` refuses the ones a command does not take: +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: | command | options it accepts | | --------------- | --------------------------------------------------------------------------------------------------------------- | diff --git a/src/lib/cli-args.ts b/src/lib/cli-args.ts index 25756670..eede8085 100644 --- a/src/lib/cli-args.ts +++ b/src/lib/cli-args.ts @@ -275,7 +275,7 @@ const USAGE = [ (c) => ` ${commandLabel(c).padEnd(COMMAND_COLUMN - 2)}${c.summary}`, ), '', - 'Options (each belongs to ONE command; passing it to another is an error):', + 'Options (each names the commands that take it; any other command refuses it):', ...OPTIONS.flatMap((opt) => optionLines(opt)), '', ENVIRONMENT, diff --git a/tests/cli-args.test.ts b/tests/cli-args.test.ts index 804bb261..8d30a81b 100644 --- a/tests/cli-args.test.ts +++ b/tests/cli-args.test.ts @@ -543,6 +543,10 @@ describe('parseCliArgs: --version and --help', () => { it('scopes every option to its commands in the full text', () => { const full = printed(['--help']); + expect(full).toContain( + 'Options (each names the commands that take it; any other command refuses it):', + ); + expect(full).not.toContain('ONE command'); expect(full).toMatch(/--archetype \s+init:/); expect(full).toMatch(/--ref \s+init: install from "latest"/); expect(full).toMatch(/\n\s+update: switch to "latest"/); From 6e23870cace26f7f21228c7d3c9d4d0def519416 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 13:16:08 +0100 Subject: [PATCH 2/2] docs: examples from pharn 0.21.0; the --help line under [Unreleased] (C4.1, CORE-174) Rebased on the 0.21.0 release: the CHANGELOG entry moves out of the released section, and the config/records examples are regenerated from a real 0.21.0 run (pharn init --yes, then pharn add n-plus-one). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 6 ++++-- docs/reference/pharn-config.md | 6 +++--- docs/reference/pharn-records.md | 2 +- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa5dcf6d..f8ef5d22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,12 +9,14 @@ Releases 0.4.0 and older are in [CHANGELOG-ARCHIVE.md](CHANGELOG-ARCHIVE.md). ## [Unreleased] -## [0.21.0] — 2026-11-17 - ### Changed - **`pharn --help` no longer says each option belongs to one command.** `--json`, `--yes`, `--ref` and `--dry-run` are taken by several, as the lines below the header already showed. The header now reads "Options (each names the commands that take it; any other command refuses it):". +## [0.21.0] — 2026-11-17 + +### Changed + - **New configs no longer carry `modules`; pharn 0.20.0 is the oldest CLI that can read them.** `pharn init` wrote `"modules": []` into every archetype `pharn.config.json` only because `pharn` 0.3.0 to 0.19.x reads a config without a `modules` array as no config at all. It no longer does, and every write (`init`, `add`, `remove`, `update`) now also drops the fields only older CLIs wrote (`modules`, `constitution`, `installedSkills`, `stackAnswers`, `isMultiTenant`) when it finds them. A config that still carries them loads in every command as before. If a teammate runs `pharn` 0.19.x or older, upgrade it first: it reports _"No pharn.config.json found"_ for a config 0.21.0 wrote, and running `pharn init` there would replace the file. ### Removed diff --git a/docs/reference/pharn-config.md b/docs/reference/pharn-config.md index 471a6c9e..2e10fbf9 100644 --- a/docs/reference/pharn-config.md +++ b/docs/reference/pharn-config.md @@ -146,18 +146,18 @@ from the list. A value that is not a list of ## Example -Written by `pharn` 0.20.0 from pharn-oss v7.22.0, in a project whose `package.json` has no +Written by `pharn` 0.21.0 from pharn-oss v7.22.0, in a project whose `package.json` has no dependencies (so the archetype is `lib`): `pharn init --yes`, then `pharn add n-plus-one`. The `models` stages and most capabilities are trimmed to `…`; the key order is the one `pharn` writes. ```json { - "pharnVersion": "0.20.0", + "pharnVersion": "0.21.0", "skillsVersion": "7.22.0", "repo": "pharn-dev/pharn-oss", "commit": "9422b97f9bcef022d240822024e75a1a49c6e278", "ref": "latest", - "installedAt": "2026-11-17T12:07:43.364Z", + "installedAt": "2026-11-17T12:15:45.108Z", "models": { "stages": { "default": { "model": "sonnet", "effort": "high" }, diff --git a/docs/reference/pharn-records.md b/docs/reference/pharn-records.md index 512d65bf..d7d8b3e2 100644 --- a/docs/reference/pharn-records.md +++ b/docs/reference/pharn-records.md @@ -20,7 +20,7 @@ missing ones; files identical to upstream are no-ops and have their records refr Five of the 546 entries the store held after the run that wrote the [`pharn.config.json` example](pharn-config.md#example) (`pharn init --yes`, then `pharn add n-plus-one`, -`pharn` 0.20.0, pharn-oss v7.22.0), hashes shortened to `…`. Keys are sorted. +`pharn` 0.21.0, pharn-oss v7.22.0), hashes shortened to `…`. Keys are sorted. ```json {