From af0df53b607acf2263a7fc799d4e0ce00be76132 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 13:10:29 +0100 Subject: [PATCH 1/2] docs(status): list every --strict failure condition in one place (C4.3, CORE-176) `pharn status --help` said "exit 1 on any outdated/modified/missing file", leaving out unreadable files, surfaces upstream no longer ships and unwired hooks, which strictFails also checks. The --strict line now names all of them and that --no-drift checks only outdated. docs/commands/status.md gains a "Strict conditions" section: the one list, with the three unwired-hook cases (hookWiringFails) and what is never a --strict input. docs/README.md, the troubleshooting exit-code table, the --json paragraph and docs/architecture.md link to it; the HOOKS bullet and the status.ts module comment no longer understate it. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + docs/README.md | 2 +- docs/architecture.md | 3 +- docs/commands/status.md | 54 ++++++++++++++++++++++++++++++----- docs/reference/json-output.md | 5 ++-- docs/troubleshooting.md | 2 +- src/commands/status.ts | 6 ++-- src/lib/cli-args.ts | 6 +++- tests/cli-args.test.ts | 19 +++++++++++- 9 files changed, 82 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f8ef5d22..a3449df7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ 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):". +- **`pharn status --help` now names every condition `--strict` fails on.** The `--strict` line said "exit 1 on any outdated/modified/missing file"; it now reads "exit 1 on an outdated install, a modified, missing or unreadable file, a surface upstream no longer ships, or an unwired hook (under --no-drift, only outdated is checked)", on both `pharn --help` and `pharn status --help`. What `--strict` checks is unchanged. The one full list, including what is never a `--strict` input (orphans, the `PRETTIER`, `NODE` and `MODELS` notes, a hook wired only in `settings.local.json`), is the new "Strict conditions" section of `docs/commands/status.md`, and `docs/README.md`, the troubleshooting exit-code table, the `status --json` summary and the JSON output reference link to it. ## [0.21.0] — 2026-11-17 diff --git a/docs/README.md b/docs/README.md index 82f881de..6772405c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,7 +18,7 @@ The CLI version (`pharn --version`) and the content version it installs (`skills - [uninstall](commands/uninstall.md) — remove PHARN, deleting only the files `pharn` wrote and you did not change - [update](commands/update.md) — re-fetch installed capabilities at the latest skills version - [list](commands/list.md) — list installed archetypes + capabilities -- [status](commands/status.md) — read-only version + local-drift check; `--strict` exits 1 on any outdated/modified/missing/unreadable file, and neither `status` nor `list` is ever blocked by another `pharn` run's lock +- [status](commands/status.md) — read-only version + local-drift check; `--strict` exits 1 on an outdated install, a modified, missing or unreadable file, a surface upstream no longer ships, or an unwired hook ([the full list](commands/status.md#strict-conditions)), and neither `status` nor `list` is ever blocked by another `pharn` run's lock ## Reference diff --git a/docs/architecture.md b/docs/architecture.md index b3b1d6af..94a2d4f0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -285,6 +285,7 @@ Strictly read-only. `settings.local.json`. - A recorded layout that differs from the clone's prints a `LAYOUT` note instead of drift. - `--no-drift` skips the clone. `--strict` exits 1 on an outdated, modified, missing, unreadable or - not-shipped-upstream finding, a layout mismatch, or an unwired hook. Orphans and the `MODELS` and `PRETTIER` notes + not-shipped-upstream finding, or an unwired hook (`strictFails`; the user-facing list is + [`status`'s Strict conditions](commands/status.md#strict-conditions)). Orphans and the `MODELS` and `PRETTIER` notes are advisory. - `--json` prints one object (`schemaVersion: 1`) through `serializeStatusReport`. diff --git a/docs/commands/status.md b/docs/commands/status.md index fa16dbc7..c4c33caa 100644 --- a/docs/commands/status.md +++ b/docs/commands/status.md @@ -6,7 +6,7 @@ from upstream? ```bash pharn status pharn status --no-drift # version check only (skips the clone) -pharn status --strict # exit 1 if outdated, differing, missing, unreadable, not shipped upstream, or a hook is unwired (for CI) +pharn status --strict # exit 1 on any strict condition (for CI): see "Strict conditions" below pharn status --json # one machine-readable report on stdout (for scripts, CI and agents) ``` @@ -149,8 +149,9 @@ current and intact. `pharn status --json` prints the same report as **one JSON object** on stdout and nothing else, on the default path and under `--no-drift`. Exit codes match text mode: `--strict` still prints the report, and -its `strict.failed` says whether it exits 1. Its keys, the `schemaVersion` 1 stability rule and a real -example are in the [JSON output reference](../reference/json-output.md#status). +its `strict.failed` says whether it exits 1, on exactly the [strict conditions](#strict-conditions). Its +keys, the `schemaVersion` 1 stability rule and a real example are in the +[JSON output reference](../reference/json-output.md#status). ## What is intentionally excluded @@ -162,7 +163,8 @@ project. The `HOOKS` section works like this: - **Missing.** It names every hook the upstream `settings.json` wires that neither project file does. Extra hooks of your own never count, and matching is textual. `--strict` exits `1` while any is - missing, or while a project settings file cannot be read. + missing, while a project settings file cannot be read, or while neither project settings file + exists (see [Strict conditions](#strict-conditions)). - **Replace, not add.** If a project file already wires the same `.claude/hooks/` script under the same event and matcher in another spelling (say, the relative `node .claude/hooks/x.cjs` where upstream anchors it on `${CLAUDE_PROJECT_DIR}`), the hook is listed under `REPLACE`, with your @@ -185,9 +187,47 @@ project. The `HOOKS` section works like this: ## Exit code Exits `0` by default, even when drift or an available update is found (it is a report) — including when -a path is unreadable. Pass `--strict` to exit `1` whenever anything is outdated, differing, missing, -unreadable, or not shipped upstream, or an upstream hook is wired in -neither `.claude/settings.json` nor `.claude/settings.local.json` — useful as a CI gate. +a path is unreadable. Pass `--strict` to exit `1` on any of the [strict conditions](#strict-conditions) +below — useful as a CI gate. + +### Strict conditions + +This is the one list of what fails `--strict`. `pharn status --help`, the +[exit-code table](../troubleshooting.md#exit-codes) and the `--json` report's `strict.failed` mean +exactly this. `--strict` exits `1` when any of these holds: + +1. **Outdated.** Your `skillsVersion` differs from the `SKILLS_VERSION` of the source the install + follows, and is not ahead of it. An install **ahead** of its source is not outdated (see + [Behavior](#behavior)). +2. **Differs.** A PHARN-owned file on disk whose content differs from upstream's (line endings in text + files are ignored). +3. **Missing.** A file your recorded capabilities or the fixed product surfaces should contribute is not + on disk. +4. **Unreadable.** An expected path that cannot be compared: a symlink, a file under a symlinked parent, + a directory or another non-regular file, an unreadable file. +5. **Not shipped upstream.** A product surface the install declares for which the fetched clone ships + no file at all. +6. **Unwired hook.** The upstream `.claude/settings.json` wires hooks (when it wires none, this + condition never holds), and one of: + - one of those hooks is wired in neither `.claude/settings.json` nor `.claude/settings.local.json`; + - either of those two files cannot be read (it could wire anything, so the answer is unknown); + - neither file exists. + +Under `--no-drift` only condition 1 is checked: there is no clone to compare conditions 2 to 6 against. + +These are reported and **never** fail `--strict`: + +- [orphaned files](#orphaned-files), in any group; +- the [`PRETTIER`](#prettier) note; +- the `NODE` mismatch (a Node older than the floor, or one whose version cannot be read); +- the `MODELS` note's REDs (a `models` block pharn-oss's rules reject); +- a hook wired **only** in `.claude/settings.local.json`, and extra hooks of your own; +- an install ahead of the source it follows, and the channel or release line; +- an installed capability this `pharn` cannot read in the fetched clone (an unknown `role` or `applies`, + or a name that fails the allowlist): it is warned about as SKIPPED and left out of the comparison; +- the layout: there is no `LAYOUT` note. An install recorded at the removed `flat` layout is refused + before any report (exit `1` with or without `--strict`, [Behavior](#behavior) step 7), a failure and + not a finding. `--strict` governs **findings**, not failures. `status` still exits `1` without it when it cannot produce a report at all: no `pharn.config.json` (or a pre-archetype one), a clone it cannot fetch, or diff --git a/docs/reference/json-output.md b/docs/reference/json-output.md index 4746d178..828b1777 100644 --- a/docs/reference/json-output.md +++ b/docs/reference/json-output.md @@ -24,7 +24,8 @@ For the three reports: So `pharn status --json | jq .` either parses or receives nothing. - **Exit codes.** `init --dry-run --json` and `update --dry-run --json` exit `0` whatever the plan contains (there is no `--strict` for a preview). `status --json` exits as text mode does: `--strict` - still prints the report and exits `1` on exactly the inputs that fail text mode, and the report's + still prints the report and exits `1` on exactly the + [strict conditions](../commands/status.md#strict-conditions) that fail text mode, and the report's `strict.failed` says the same. - **Escaped output.** Characters a terminal would interpret (control characters, Unicode format characters, U+2028/U+2029) are written as `\uXXXX` escapes, so a `cat` of the output cannot move or @@ -372,7 +373,7 @@ The version, drift and hook report, on the default path and under `--no-drift`. | `unknownCapabilities` | `Unknown[]` or `null` | `null` under `--no-drift`. | | `orphans` | `Orphan[]` or `null` | `null` under `--no-drift` or without a usable `pharn.records.json`. Never a `--strict` input. | | `prettierignore` | `IgnoreEdit` or `null` | What `pharn update` would do to `.prettierignore`; `null` when there is nothing to say or no usable `pharn.records.json`. Answered under `--no-drift` too. Never a `--strict` input. | -| `strict` | `{enabled, failed}` | `--strict` passed, and whether it exits `1`. | +| `strict` | `{enabled, failed}` | `--strict` passed, and whether it exits `1` (the [strict conditions](../commands/status.md#strict-conditions)). | Unlike the other two reports, `status --json` reports an empty or skipped part as `null` or `[]` rather than leaving the key out; only `hooks.replace` is absent when empty. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 27770623..2a6e49b6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -14,7 +14,7 @@ | 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 anything outdated, modified, missing or unreadable | 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 | diff --git a/src/commands/status.ts b/src/commands/status.ts index ccfb814a..8250976b 100644 --- a/src/commands/status.ts +++ b/src/commands/status.ts @@ -60,8 +60,10 @@ import type { InstalledCapability, PharnConfig } from '../types.js'; * section)? Never writes — fixing is `pharn update` / `pharn add`. * * Default clones once for both sections; `--no-drift` checks the version only. - * `--strict` exits 1 on anything outdated, modified or missing, or an unwired - * upstream hook. The work is done once into ONE + * `--strict` exits 1 on an outdated install, a modified, missing or unreadable + * file, a declared surface upstream no longer ships, or an unwired upstream + * hook — `strictFails` (lib/status-report.ts) is the one predicate, and + * docs/commands/status.md lists it. The work is done once into ONE * `StatusReport` (lib/status-report.ts): `--json` prints it, the text notes are * rendered from it, and both read `--strict`'s verdict off it. `--json` emits * ONE object on stdout and nothing else; diagnostics and failures go to diff --git a/src/lib/cli-args.ts b/src/lib/cli-args.ts index eede8085..7ae0990d 100644 --- a/src/lib/cli-args.ts +++ b/src/lib/cli-args.ts @@ -159,7 +159,11 @@ const OPTIONS: readonly OptionSpec[] = [ uses: [ { commands: ['status'], - text: ['exit 1 on any outdated/modified/missing file'], + text: [ + 'exit 1 on an outdated install, a modified, missing or unreadable', + 'file, a surface upstream no longer ships, or an unwired hook', + '(under --no-drift, only outdated is checked)', + ], }, ], }, diff --git a/tests/cli-args.test.ts b/tests/cli-args.test.ts index 8d30a81b..b942cecb 100644 --- a/tests/cli-args.test.ts +++ b/tests/cli-args.test.ts @@ -620,10 +620,27 @@ describe('parseCliArgs: --version and --help', () => { it('describes an option on its command page without the command prefix', () => { const page = printed(['status', '--help']); - expect(page).toMatch(/--strict +exit 1 on any outdated/); + expect(page).toMatch(/--strict +exit 1 on an outdated install/); expect(page).not.toMatch(/status: /); }); + it('names every condition `strictFails` checks on the `--strict` line', () => { + // strictFails (lib/status-report.ts): outdated, modified/missing/unreadable + // files, a surface upstream no longer ships, an unwired hook. + const help = printed(['status', '--help']).replace(/\s+/g, ' '); + for (const condition of [ + 'outdated', + 'modified', + 'missing', + 'unreadable', + 'upstream no longer ships', + 'unwired hook', + 'under --no-drift, only outdated', + ]) { + expect(help, condition).toContain(condition); + } + }); + it('shows only the use of a shared option that belongs to the command', () => { const page = printed(['list', '--help']); expect(page).toMatch(/--json +emit the inventory as JSON/); From 3e8a29056d6bbfee1c3e65f00e986735f6f7ecd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 13:16:14 +0100 Subject: [PATCH 2/2] docs(architecture): drop the removed LAYOUT note from the status flow (C4.3, CORE-176) The flat layout is gone, so status prints no LAYOUT note. Co-Authored-By: Claude Opus 5.5 --- docs/architecture.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 94a2d4f0..bcdc9773 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -283,7 +283,6 @@ Strictly read-only. not read the records; only `update` can tell an upgrade from a skip. - **Hooks** (`lib/hook-wiring.ts`): upstream's hook entries against the project's `settings.json` ∪ `settings.local.json`. -- A recorded layout that differs from the clone's prints a `LAYOUT` note instead of drift. - `--no-drift` skips the clone. `--strict` exits 1 on an outdated, modified, missing, unreadable or not-shipped-upstream finding, or an unwired hook (`strictFails`; the user-facing list is [`status`'s Strict conditions](commands/status.md#strict-conditions)). Orphans and the `MODELS` and `PRETTIER` notes