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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ Releases 0.4.0 and older are in [CHANGELOG-ARCHIVE.md](CHANGELOG-ARCHIVE.md).

## [Unreleased]

### 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
Expand Down
49 changes: 27 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
Expand All @@ -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/<command>/<name>/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/<command>/<name>/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.

Expand Down Expand Up @@ -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).

Expand All @@ -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

Expand Down Expand Up @@ -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/<timestamp>/` 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
Expand Down
7 changes: 4 additions & 3 deletions docs/commands/add.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down
15 changes: 10 additions & 5 deletions docs/commands/init.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -211,7 +215,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:

Expand Down Expand Up @@ -476,7 +481,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
Expand Down
5 changes: 3 additions & 2 deletions docs/commands/list.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 5 additions & 3 deletions docs/commands/remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 <list>` 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
Expand Down
6 changes: 4 additions & 2 deletions docs/commands/update.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,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:
Expand Down Expand Up @@ -616,7 +617,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

Expand Down
8 changes: 6 additions & 2 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
34 changes: 24 additions & 10 deletions docs/reference/pharn-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,21 +146,33 @@ from the list. A value that is not a list of

## Example

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.4.0",
"skillsVersion": "3.0.2",
"pharnVersion": "0.21.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:15:45.108Z",
"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"
}
```

Expand Down Expand Up @@ -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).
Expand Down
Loading
Loading