fix(add): accept the version a user-edit-withheld update applied (PHARN-05)

[PrzemekGalarowicz]

What this changes

Keeping a single local edit could block pharn add for good.

Reproduced:

1. init at 6.11.1, then edit one file locally.
2. update --yes to 6.17.1, twice. Each run reports "skipped 1" and the config stays at 6.11.1.
3. pharn add a11y exits 1: "Skills version mismatch … run pharn update first". Running pharn update again changes nothing, so the advice loops.

The fix:

• update: when the only skipped files are the user's own edits (modified / unrecorded), every other file is already at the new version. update now records that version in pharn.config.json as pendingSkillsVersion. It is a new optional field, validated against VERSION_RE when the config is read. The next complete update removes it. Other skip kinds (unverifiable, unreadable) can leave most of the project on the old version, so they do not record it.
• add: accepts a clone at pendingSkillsVersion. In that case it keeps the config's existing skillsVersion and commit (addStamp), and stamps the records file with the same pair. So add never claims an upgrade that the user's edited files did not receive. add still never raises skillsVersion.
• Refusal message: when add still refuses, it now names the options that actually work: revert the edits, or run update --force (which backs them up first).
• Docs: docs/commands/add.md, docs/reference/pharn-config.md and CLAUDE.md updated.

Built with /pharn-dev-ship; stage artifacts are in .dev/features/add-after-withheld-update/. Results:

• validate: exit 0
• regress: no-regressions
• verify: PASS

Type of change

• feat — new stack option, wizard step, or command capability
• fix — bug fix
• docs — docs-only change
• chore / refactor — tooling or internal restructure, no behavior change

Area(s) touched

types | lib/pharn-config | commands/update, add | docs

Checklist

• Read the existing file(s) before editing; followed the ESM .js-extension import convention.
• Updated the matching tests. 8 new cases fail on the old source.
• Updated the relevant docs/ pages.
• Preserved the security invariants.

Quality gates

• npm run check passes locally (1332/1332; non-root user, node 22).
• npm run build succeeds (left to CI).
• npm run test:coverage passes (left to CI).

Notes for the reviewer

The main thing to check is that add keeps the existing version and commit when it installs at pendingSkillsVersion. The plan review (grill) caught that add would otherwise record the clone's newer version and commit, hiding the unfinished upgrade.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TvcuVhk8hTeDskp5pAJhnc

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 8132540c-d8ee-4915-87d2-1252fcd12e01

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}