Skip to content

docs: trim update.md, troubleshooting and README; rare update states move to a reference page (C4.6, CORE-179) - #421

Merged
PrzemekGalarowicz merged 1 commit into
mainfrom
przemek/core-179-trim-docs
Nov 17, 2026
Merged

PrzemekGalarowicz merged 1 commit into
mainfrom
przemek/core-179-trim-docs

Conversation

@PrzemekGalarowicz

@PrzemekGalarowicz PrzemekGalarowicz commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Delivers C4.6 (CORE-179), the last task of epic CORE-153. Docs only: no src/ or tests/ change, no protected file, no version bump. The CHANGELOG gets link-target fixes only, with no new entry.

File Before After Cap
docs/commands/update.md 901 349 350
docs/troubleshooting.md 972 448 450
README.md 508 246 250
docs/reference/update-advanced.md (new) — 314 —
docs/reference/project-lock.md (new) — 90 —

Acceptance checklist

  • update.md ≤ 350, troubleshooting.md ≤ 450, README.md ≤ 250 (349 / 448 / 246).
  • No content is lost. Each moved section keeps its exact heading, so its anchor still works, and it is linked from where it was (update.md's "Less common situations" list, the troubleshooting stubs). The full ledger is below. A separate old-vs-new fact audit ran before review, and every gap it found was restored or corrected.
  • No src file or function name is left in README, docs/getting-started.md, docs/troubleshooting.md, docs/commands/ or docs/reference/. The grep output is below.
  • npm run lint:md passes. No test pins doc text (checked by grep in tests/), so no test changed.

Ticket items

  • update.md: keeps the synopsis, the behaviour in 6 steps, the decision table and skip labels, --force and backups, the dry run, the channels and CI use. The rare states move to docs/reference/update-advanced.md, and the JSON keys stay in json-output.md (C4.5).
  • troubleshooting.md: opens with the exit-code table (new row: 130 / 143 on SIGINT / SIGTERM, from fatal-signal.ts and project-lock.ts), then a "Common problems" index of 8 symptoms. Version history is cut; every cut passage was already in CHANGELOG.md / CHANGELOG-ARCHIVE.md.
  • README.md: keeps what/why, the quick start with the test-runner note, the commands table, the safety bullets and the links. "After install" is now three bullets plus links to pharn-oss's README and LIMITS.md.
  • getting-started.md: the shadcn step and the layout paragraph are gone.
  • Single source. Detection rules live in docs/commands/init.md "3. Detect archetypes", which gains the two monorepo rules that only troubleshooting had. Install locations live in docs/getting-started.md "What you get". README, getting-started, troubleshooting and the overwrite/remove-by-hand text link to them.
  • src names removed: lib/hash.ts (troubleshooting), lib/install-manifest.ts (init.md), the Source: links plus isArchetypeConfig (pharn-config.md), runInstallArchetype / collectExpectedInstallPaths plus the Source: link (pharn-records.md).
  • remove.md "Earlier releases…" aside is deleted.
  • "byte-identical to 0.10.0" ×9: moot, because C4.5 already removed them. The one remaining "byte-identical to an interactive run" (--yes) is rephrased.

Behaviour that no longer exists (deleted, not moved)

  • "The root-footprint migration" (update.md) was removed by refactor: remove the flat layout and the root migration (CORE-155) [v0.21.0] #412. No code deletes root docs any more, and plan.rootMigration is always null (already documented in json-output.md). What is still true moved: a recorded root THREAT-MODEL.md/LIMITS.md is an ORPHANED file (update-advanced.md "Orphaned files"), and the advice to move a root memory-bank/ or pharn.spec-template.md by hand is in getting-started.
  • "First update after upgrading" and "every install before 0.4.0 is unverifiable" (update.md, troubleshooting): a pre-0.4.0 config has no layout key, and loadArchetypeConfig refuses it with FLAT_LAYOUT_MESSAGE before any planning (pharn-config.ts:535). The no-usable-store case that still happens is kept (update-advanced.md "No usable records store").
  • "Before you confirm": update.md said update re-plans after the confirm and can stop with "The capabilities this update would change are no longer what you confirmed". That message is not in src/: update plans once, under the lock taken before the plan. Also removed: "a run refused by another pharn process's lock has already downloaded it", which contradicts the lock coming first.
  • "nothing to move" and "no root doc to delete" in "When there is nothing to change": no layout moves or root-doc deletes exist any more.
  • Version-history asides: the constitution overwrite before 0.4.0, the stamp-as-gate, the stderr fix through 0.3.2, colour before 0.13.0, the executable unit before 0.18.0, the Node 20.13 floor before 0.8.0, the codeload/degit proxy change, the argv "used to…" stories, updatedAt before 0.20.0, the .gitignore lines in 0.16.0 and .prettierignore in 0.17.0. All are in the CHANGELOG already.

Ledger: old section → new home

docs/commands/update.md

Old section Now
Synopsis, options, Behavior (8 steps), Concurrency update.md: synopsis, Behavior (6 steps; Concurrency folded into step 1)
Edits made while update waits for your answer update.md (same heading)
Previewing an update, JSON output update.md (same headings)
What happens to your capability list, Dropped capabilities are deleted, removals-are-not-permanent note update.md (same headings; the note is folded in)
When pharn cannot read a capability upstream update-advanced.md (same heading)
pharn is too old for the current pharn-oss troubleshooting.md (same heading, where it already was)
The decision table, The skip labels update.md (same headings); the hard-link paragraph → update-advanced.md "Writes replace the file"
The executable unit is upgraded all or none update-advanced.md (same heading)
Orphaned files update-advanced.md (same heading)
--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 update.md (same headings)
The models block update-advanced.md (same heading)
First update after upgrading deleted (dead); the live part → update-advanced.md "No usable records store"
Missing files at the same skills version; A surface added by a newer CLI; The review lens agent update-advanced.md "Missing files at the same skills version" (merged)
A records store from an interrupted run update-advanced.md (same heading) + "No usable records store"
Layout migrations update-advanced.md "An install recorded at the flat layout"
The root-footprint migration deleted (dead), see above
A surface pharn-oss does not ship, .gitignore, .prettierignore, What is protected by default update-advanced.md (same headings)
(dry-run "features-README moves") update-advanced.md "The features README at the project root" (the live featuresReadmeRelocation note)

docs/troubleshooting.md: every section keeps its heading. History and repetition are cut, and these parts moved:

Old part Now
Lock: why it exists, every stale-lock break rule, recycled pid, clock, pharn/.lock directory, .lock.<pid>.<hex>, two versions, pharn must be a directory docs/reference/project-lock.md (the plan's approved fallback); the troubleshooting "If the lock outlives its owner" heading stays as a stub that links there
Detection rules (dependencies vs devDependencies, root package.json gating, bounds, monorepo) init.md "3. Detect archetypes"; the troubleshooting subsections keep the symptom and the --archetype fix
Install-target / removal path lists getting-started "What you get" (linked), with the exceptions kept inline
degit cache story cut to the size, the paths table and the delete advice
Local development table the same three fixes, as one paragraph

README.md

Old section Now
What gets installed (table, increment files, .gitignore details, old root footprint) README paragraph + getting-started "What you get" (table, increment-directory file list, pharn/.lock*, the old .pharn/ line, moving a root memory-bank/) + init.md .gitignore
After install (hooks, write-guard postures, Stop guard) three bullets (wiring, Stop guard, update never edits settings + Bash bypass) + pharn-oss README / LIMITS.md for the postures, as the ticket asks
Day-to-day workflow (stage table, triage/supervise history, spec template) stage table → getting-started "After init" (which keeps the triage/supervise text, plus "you can run /pharn-triage yourself" and the spec-template write-guard note)
CLI commands scripting notes, Agent skills, Safety model, Current scope, Documentation, Development, Security README (tightened; detection → init.md link; scripts table → one sentence)

Grep: no src file or function name in the user docs

srcnames-grep.sh checks for src paths, markdown links into src/, src basenames with .ts/.js, and every exported function/const/class name (≥ 6 chars) under src/, over README.md, docs/getting-started.md, docs/troubleshooting.md, docs/commands, docs/reference:

== src/lib/steps/commands .ts|.js paths
docs/commands/uninstall.md:58:src/app.ts
docs/reference/pharn-records.md:206:src/app.ts
== markdown links into src/
== src basenames with .ts/.js
docs/reference/json-output.md:498:`node <checkout>/dist/index.js`), run on 2026-11-17 against the pharn-oss v7.22.0 release, in a new
== exported functions, consts and classes (len>=6)
== done

The remaining hits are not pharn source: src/app.ts is an example of a user's file (uninstall.md, pharn-records.md), and dist/index.js is the shipped bin in json-output.md's "How the examples were made". Config and JSON keys such as skillsVersion and frozenCapabilities are documented fields, not src names.

Links

check-anchors.mjs resolves every relative link and #anchor in README, CHANGELOG, CONTRIBUTING, SECURITY and docs/**:

CHANGELOG.md:82: missing anchor docs/support-policy.md#the-flat-layout-is-deprecated
1 broken link(s) in 25 files

That link is broken on main too and is not from this PR. The other link that was broken on main (update.md#compact-…) now points at json-output.md#--compact. CHANGELOG changes are link targets only, checked by diffing with link targets stripped.

Pipeline (/pharn-dev-ship, gated)

Stage Result
build (validate.mjs) exit 0 (FLOOR: GREEN)
regress (regression-report.json) no-regressions
verify (verify-report.json) PASS (test, validate, lint, format:check, lint:md, typecheck, line-caps, anchors, srcnames)
review 0 floor findings, 5 advisory (.dev/features/core-179-trim-docs/REVIEW.md)

Two advisory review findings worth a look:

  • All three files are within 1–4 lines of their caps, and no CI gate enforces the caps.
  • src/commands/update.ts:441,460 comments still mention the removed root migration and root-doc deletes. That is a code follow-up outside this docs ticket.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Reorganized the project overview, setup guidance, installation details, workflow, CLI usage, and troubleshooting information.
    • Added references covering project locks and advanced update scenarios, including file handling and interrupted updates.
    • Clarified installation detection limits, update steps and options, lock behavior, and command outcomes.
    • Updated links throughout the documentation and refreshed guidance for workflows, scripting, and development checks.

…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 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

Walkthrough

This pull request reorganizes the README and project documentation. It revises setup, command, reference, and troubleshooting guidance, and adds references for advanced update situations and project locking. No runtime changes are described.

Changes: Project documentation

Layer / File(s) Summary
Project overview and setup
README.md, docs/getting-started.md
The guides condense setup and installation details and revise descriptions of workflow, safety, archetype detection, development, and project scope.
Update workflow and advanced cases
docs/commands/update.md, docs/reference/update-advanced.md, CHANGELOG.md, docs/README.md, docs/commands/add.md, docs/commands/status.md, docs/reference/deletes.md, docs/reference/json-output.md, docs/reference/pharn-config.md, docs/reference/pharn-records.md, docs/support-policy.md
The update guide is reorganized and links less common situations to a new advanced reference. The reference documents executable-unit holds, orphaned files, records-store conditions, file handling, and other update cases. Related links are updated.
Project-lock reference
docs/reference/project-lock.md, docs/troubleshooting.md, docs/reference/deletes.md
The new lock reference documents which commands lock, lock lifecycle, stale-lock rules, and refusal cases. Troubleshooting and deletion guidance link to the reference.
Command and configuration references
docs/commands/init.md, docs/commands/remove.md, docs/reference/pharn-config.md, docs/reference/pharn-records.md
The guides revise detection and migration descriptions, install-target wording, and configuration and records explanations. The remove guide removes a note about earlier --yes behavior.
Troubleshooting guidance
docs/troubleshooting.md
The guide revises documented exit outcomes, prerequisites, update and backup cases, detection, proxy rules, command-line errors, and manual-removal steps.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Merge Risk: Low · up to 59fbf

This documentation-only change has several statements that do not match behavior. The quick start can continue in the wrong directory and commit its contents if app creation fails. The stale-lock advice can lead a reader to delete a live remote holder's lock. A few update and record-store descriptions are inaccurate. None of this changes runtime behavior, and the fixes are small wording edits.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

Copy link
Copy Markdown

pharn

🛡️ pharn-ci · ✅ Pass

Tip

Pass · This change adds no coverable lines; 29 agent setup files found.

Verdict Diff coverage Test integrity Agent setup
✅ Pass no coverable lines none (block) 29 files

🧪 Diff coverage

No coverable lines changed.

🔍 Test integrity

No test-integrity findings (mode: block).

💬 Messages (1)

  • ℹ️ NO_COVERABLE_CHANGES No added lines are tracked by the coverage report; nothing to measure.
    • Hint: Nothing to do if the change has no code; otherwise check that the coverage report includes the changed files.

🤖 Agent setup (29 files)

Agent setup: 29 files · claude-code

Agent setup files (29)
Path Kind
.claude/commands/pharn-dev-build.md claude-command
.claude/commands/pharn-dev-eval.md claude-command
.claude/commands/pharn-dev-grill.md claude-command
.claude/commands/pharn-dev-memory-promote.md claude-command
.claude/commands/pharn-dev-plan.md claude-command
.claude/commands/pharn-dev-regress.md claude-command
.claude/commands/pharn-dev-review.md claude-command
.claude/commands/pharn-dev-ship.md claude-command
.claude/commands/pharn-dev-verify.md claude-command
.claude/hooks/enforce-writes-scope.cjs claude-hook
.claude/hooks/enforce-writes-scope.test.cjs claude-hook
.claude/hooks/git-worktree-fixture.cjs claude-hook
.claude/hooks/protect-trusted-paths.cjs claude-hook
.claude/hooks/protect-trusted-paths.test.cjs claude-hook
.claude/hooks/session-root.cjs claude-hook
.claude/hooks/session-root.test.cjs claude-hook
.claude/hooks/set-writes-scope.cjs claude-hook
.claude/hooks/set-writes-scope.test.cjs claude-hook
.claude/settings.json claude-settings
.claude/skills/phargus-diagnose claude-skill
.claude/skills/phargus-memory claude-skill
.claude/skills/phargus-rules claude-skill
.claude/skills/phargus-setup claude-skill
.claude/skills/phargus-verify claude-skill
.claude/skills/pharn-ci-cover claude-skill
.claude/skills/pharn-ci-explain claude-skill
.claude/skills/pharn-ci-install claude-skill
.claude/skills/pharn-cli claude-skill
CLAUDE.md claude-md

pharn-ci 0.10.0 · report schema v2 · coverage format lcov

@PrzemekGalarowicz
PrzemekGalarowicz merged commit 21df090 into main Nov 17, 2026
14 of 15 checks passed
@PrzemekGalarowicz
PrzemekGalarowicz deleted the przemek/core-179-trim-docs branch November 17, 2026 13:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant