Skip to content

docs: one true statement about what PHARN deletes (C4.2, CORE-175) - #416

Merged
PrzemekGalarowicz merged 1 commit into
mainfrom
przemek/core-175-what-pharn-deletes
Nov 17, 2026
Merged

PrzemekGalarowicz merged 1 commit into
mainfrom
przemek/core-175-what-pharn-deletes

Conversation

@PrzemekGalarowicz

@PrzemekGalarowicz PrzemekGalarowicz commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Linear: CORE-175 (epic CORE-153).

Adds docs/reference/deletes.md, What PHARN deletes: every delete a pharn command makes, traced from the current code (rmSync/unlinkSync/rmdirSync/rename-away in src/), the check behind each, and what is never deleted. The command pages link to it, and every sentence that contradicted the code is replaced.

Ticket checklist

Delete paths (built from current main, not the ticket's 0.18.2 list):

  • 1. update / re-run init: a dropped capability's directory, backed up first (capability-removal.ts, capability-dir.ts).
  • 2. Root migration deletes root THREAT-MODEL.md/LIMITS.md: moot, refactor: remove the flat layout and the root migration (CORE-155) [v0.21.0] #412 removed the root migration. The page lists them as orphans that update never deletes; README.md's stale "deletes the two docs" sentence is fixed.
  • 3. remove: one capability directory, unproven files backed up, records pruned.
  • 4. uninstall: recorded files at their recorded hash (incl. .claude/settings.json a fresh init created, per C2.4), empty dirs, the records, the config (backed up), an empty pharn/.
  • 5. Root migration renames memory-bank//pharn.spec-template.md: moot, removed (C1.1 / refactor: remove the flat layout and the root migration (CORE-155) [v0.21.0] #412). Listed under "never deleted".
  • 6. pharn's own state: the temp download (also on SIGINT/SIGTERM), pharn/.lock, a stale lock's corpse (only by the breaker that made it; a stranded one never), an empty pharn/ the lock created, a failed write's temp file. The "stale legacy root .pharn.lock" path is moot: removed in v0.20.0.
  • 7. Record entries pruned; no file touched.
  • "Never deleted" list: unrecorded/edited files outside a removed/dropped capability dir, orphans and flat leftovers (except uninstall of unchanged ones), .claude/settings.json (except uninstall of the one init created), .claude/settings.local.json, pharn/.backup/, user data incl. root .pharn-backup/ and .pharn/, .gitignore/.prettierignore lines, anything behind a symlink.

Contradicting sentences:

  • README.md "Nothing deletes an orphan" → update never deletes one; uninstall removes the unchanged ones; link.
  • README.md root-footprint paragraph (still described the removed migration deleting the docs) → true now; link.
  • README.md "The only thing it deletes…" → kept as a true statement, plus link. uninstall row: "Never touches .claude/settings.json" → "a .claude/settings.json it did not create".
  • docs/commands/status.md "no pharn command can clear one — update never deletes" → link.
  • docs/commands/init.md "(init never deletes)": now reads "(init never deletes them)" about the flat copies, which is true; the dropped-capabilities section links the page.
  • docs/commands/update.md "the only thing update deletes" (x2) → true restatement + link; the ORPHANED note sample matches the new string.
  • docs/reference/pharn-records.md "a record key never causes a write or a delete" → "never causes a write, and causes a delete only in uninstall".
  • docs/roadmap.md orphans row "nothing is deleted" → "update keeps them".
  • docs/architecture.md orphans "It is never deleted" → "update never deletes it"; deletes bullet links the page.
  • docs/README.md links the new page; remove.md and uninstall.md link it.
  • src/lib/orphans.ts CLI string "pharn never deletes them" → "pharn update never deletes them"; tests/orphans.test.ts and tests/root-migration.test.ts assertions rewritten (no it removed). CHANGELOG [Unreleased] → ### Fixed line.
  • LIMITS.md:72 (src/commands/update.ts:452 citation and "update never deletes"): LIMITS.md is human-owned and hook-protected, so it is fixed by a patch script the maintainer runs; it lands as a follow-up commit on this branch. The same patch fixes §1d's "reports nothing" (orphans are now named in the ORPHANED note).
  • "After C1.1 and C2.4 land, the section is updated in the same PR as each": both had already landed, so the section is written against the code after them.

Acceptance grep (never delete, nothing deletes, only thing … deletes) over README.md docs/: every hit is now a true, scoped statement; the one in LIMITS.md goes with the patch.

Test changes (pharn-ci TI07)

The behaviour change is intended. tests/root-migration.test.ts ("previews in the future tense") and tests/orphans.test.ts change only the expected text of the ORPHANED note, from pharn never deletes to `pharn update` never (the orphans test also asserts the old false sentence is gone). The old text was false: pharn uninstall deletes an orphan that still equals its record (src/lib/uninstall-plan.ts).

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 19 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between ee7844d and 6c182ee.

Files selected for processing: 16

  • CHANGELOG.md
  • README.md
  • docs/README.md
  • docs/architecture.md
  • docs/commands/init.md
  • docs/commands/remove.md
  • docs/commands/status.md
  • docs/commands/uninstall.md
  • docs/commands/update.md
  • docs/reference/deletes.md
  • docs/reference/pharn-records.md
  • docs/roadmap.md
  • src/lib/orphans.ts
  • tests/orphans.test.ts
  • tests/root-migration.test.ts
  • tests/status-report.test.ts
  • 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 · ⚠️ Warn

Warning

Warn · This change adds no coverable lines; 1 test-integrity finding; 29 agent setup files found.

Verdict Diff coverage Test integrity Agent setup
⚠️ Warn no coverable lines ⚠️ 1 finding 29 files

🧪 Diff coverage

No coverable lines changed.

🔍 Test integrity

  • ⚠️ TI07 tests/root-migration.test.ts:534 — The test "the ROOT MIGRATION note › previews in the future tense" changed only an expected value of its toContain assertion, in a change that also edits source files.
    • Hint: Check each new expected value against what the code should do, not what it now returns; if the behaviour change is meant, say so in the PR so a reviewer can confirm it.
Tests changed: +0 −0 ~2
Test file Added Removed Modified Renamed
tests/orphans.test.ts 0 0 1 0
tests/root-migration.test.ts 0 0 1 0

💬 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 force-pushed the przemek/core-175-what-pharn-deletes branch from b57fab5 to 561cf47 Compare November 17, 2026 12:49
Add docs/reference/deletes.md, the one list of every delete a pharn
command makes (dropped capability directories in update/init, remove,
uninstall, record pruning, and pharn's own download, lock, empty pharn/
and temp files), the check behind each, and what is never deleted.
Link it from docs/README.md and the command pages, and replace the
sentences that contradicted the code: "Nothing deletes an orphan",
"no pharn command can clear one", the removed root-migration delete in
README.md, "a record key never causes a write or a delete", the
roadmap's "nothing is deleted", and uninstall "never touches
.claude/settings.json".

The ORPHANED note now says "`pharn update` never deletes them" instead
of "pharn never deletes them": uninstall deletes unchanged orphans.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@PrzemekGalarowicz
PrzemekGalarowicz force-pushed the przemek/core-175-what-pharn-deletes branch from 561cf47 to 6c182ee Compare November 17, 2026 12:52
@PrzemekGalarowicz
PrzemekGalarowicz merged commit 731ee10 into main Nov 17, 2026
15 checks passed
@PrzemekGalarowicz
PrzemekGalarowicz deleted the przemek/core-175-what-pharn-deletes branch November 17, 2026 12:58
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