Repository navigation
docs: trim update.md, troubleshooting and README; rare update states move to a reference page (C4.6, CORE-179) - #421
Conversation
…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>
|
Caution Review failedThe pull request is closed. Walkthrough
Merge Risk:
|
🛡️ pharn-ci · ✅ PassTip Pass · This change adds no coverable lines; 29 agent setup files found.
🧪 Diff coverageNo coverable lines changed. 🔍 Test integrityNo test-integrity findings (mode: block). 💬 Messages (1)
🤖 Agent setup (29 files)Agent setup: 29 files · claude-code Agent setup files (29)
pharn-ci 0.10.0 · report schema v2 · coverage format lcov |
Delivers C4.6 (CORE-179), the last task of epic CORE-153. Docs only: no
src/ortests/change, no protected file, no version bump. The CHANGELOG gets link-target fixes only, with no new entry.docs/commands/update.mddocs/troubleshooting.mdREADME.mddocs/reference/update-advanced.md(new)docs/reference/project-lock.md(new)Acceptance checklist
update.md≤ 350,troubleshooting.md≤ 450,README.md≤ 250 (349 / 448 / 246).docs/getting-started.md,docs/troubleshooting.md,docs/commands/ordocs/reference/. The grep output is below.npm run lint:mdpasses. No test pins doc text (checked by grep intests/), so no test changed.Ticket items
--forceand backups, the dry run, the channels and CI use. The rare states move todocs/reference/update-advanced.md, and the JSON keys stay in json-output.md (C4.5).SIGINT/SIGTERM, fromfatal-signal.tsandproject-lock.ts), then a "Common problems" index of 8 symptoms. Version history is cut; every cut passage was already inCHANGELOG.md/CHANGELOG-ARCHIVE.md.docs/commands/init.md"3. Detect archetypes", which gains the two monorepo rules that only troubleshooting had. Install locations live indocs/getting-started.md"What you get". README, getting-started, troubleshooting and the overwrite/remove-by-hand text link to them.lib/hash.ts(troubleshooting),lib/install-manifest.ts(init.md), theSource:links plusisArchetypeConfig(pharn-config.md),runInstallArchetype/collectExpectedInstallPathsplus theSource:link (pharn-records.md).--yes) is rephrased.Behaviour that no longer exists (deleted, not moved)
plan.rootMigrationis alwaysnull(already documented in json-output.md). What is still true moved: a recorded rootTHREAT-MODEL.md/LIMITS.mdis anORPHANEDfile (update-advanced.md "Orphaned files"), and the advice to move a rootmemory-bank/orpharn.spec-template.mdby hand is in getting-started.unverifiable" (update.md, troubleshooting): a pre-0.4.0 config has nolayoutkey, andloadArchetypeConfigrefuses it withFLAT_LAYOUT_MESSAGEbefore any planning (pharn-config.ts:535). The no-usable-store case that still happens is kept (update-advanced.md "No usable records store").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.updatedAtbefore 0.20.0, the.gitignorelines in 0.16.0 and.prettierignorein 0.17.0. All are in the CHANGELOG already.Ledger: old section → new home
docs/commands/update.md
pharn is too old for the current pharn-oss--forceandpharn/.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 truemodelsblock.gitignore,.prettierignore, What is protected by defaultfeaturesReadmeRelocationnote)docs/troubleshooting.md: every section keeps its heading. History and repetition are cut, and these parts moved:
pharn/.lockdirectory,.lock.<pid>.<hex>, two versions,pharnmust be a directorydocs/reference/project-lock.md(the plan's approved fallback); the troubleshooting "If the lock outlives its owner" heading stays as a stub that links therepackage.jsongating, bounds, monorepo)--archetypefixREADME.md
.gitignoredetails, old root footprint)pharn/.lock*, the old.pharn/line, moving a rootmemory-bank/) + init.md.gitignoreupdatenever edits settings + Bash bypass) + pharn-oss README / LIMITS.md for the postures, as the ticket asks/pharn-triageyourself" and the spec-template write-guard note)Grep: no src file or function name in the user docs
srcnames-grep.shchecks for src paths, markdown links intosrc/, src basenames with.ts/.js, and every exported function/const/class name (≥ 6 chars) undersrc/, over README.md, docs/getting-started.md, docs/troubleshooting.md, docs/commands, docs/reference:The remaining hits are not pharn source:
src/app.tsis an example of a user's file (uninstall.md, pharn-records.md), anddist/index.jsis the shipped bin in json-output.md's "How the examples were made". Config and JSON keys such asskillsVersionandfrozenCapabilitiesare documented fields, not src names.Links
check-anchors.mjsresolves every relative link and#anchorin README, CHANGELOG, CONTRIBUTING, SECURITY and docs/**:That link is broken on
maintoo and is not from this PR. The other link that was broken onmain(update.md#compact-…) now points atjson-output.md#--compact. CHANGELOG changes are link targets only, checked by diffing with link targets stripped.Pipeline (/pharn-dev-ship, gated)
validate.mjs)regression-report.json)no-regressionsverify-report.json)PASS(test, validate, lint, format:check, lint:md, typecheck, line-caps, anchors, srcnames).dev/features/core-179-trim-docs/REVIEW.md)Two advisory review findings worth a look:
src/commands/update.ts:441,460comments 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