Skip to content

docs: LIMITS, THREAT-MODEL, SECURITY and roadmap match the code (C4.4, CORE-177) - #419

Merged
PrzemekGalarowicz merged 3 commits into
mainfrom
przemek/core-177-guarantee-docs
Nov 17, 2026
Merged

PrzemekGalarowicz merged 3 commits into
mainfrom
przemek/core-177-guarantee-docs

Conversation

@PrzemekGalarowicz

Copy link
Copy Markdown
Member

Part of epic CORE-153 (C4). Docs only, no CLI output change, so no CHANGELOG line.

This PR carries SECURITY.md and docs/roadmap.md. THREAT-MODEL.md and LIMITS.md are human-owned and hook-protected, so their changes are in a patch script (patch-core-177.py) that a maintainer runs. It will be committed into this PR afterwards. The script applies cleanly on top of origin/main in either order with C4.2's patch-core-175.py, because the two never edit the same text.

Checklist (ticket items)

  • THREAT-MODEL typeflag x "skipped": already fixed on main (§2 lists x under REJECT). Nothing to do.
  • THREAT-MODEL AbortController timeout cleared in finally: (patch) every fetch now goes through fetchCapped (src/lib/fetch-capped.ts) with the withDeadline hard deadline (src/lib/deadline.ts, a Promise.race). The §3 table names the release resolve and fetchCapped.
  • THREAT-MODEL Node 20–23 proxy rows: (patch) §2 and §4b now describe the 24.2.0 floor's opt-in. LIMITS §3a keeps one sentence for add/status, which still run below the floor (only init/update refuse there).
  • SECURITY "default main channel … opt-in --ref latest": the verified release is now the default. main is the opt-in, along with its degraded mode.
  • SECURITY root layout, .pharn.lock/.pharn-backup/: everything installs under pharn/ and .claude/ (named in full). The lock and backups are pharn/.lock and pharn/.backup/<timestamp>/. The license goes only to pharn/LICENSE, and the appended .gitignore/.prettierignore lines are listed.
  • THREAT-MODEL @main framed as the default (§2 item 6, §4c): (patch) these now say "the install's channel: the newest verified release by default, or @main". The "One resolve" bullet and the fetch-boundary lead name the release resolve first.
  • LIMITS "resolves the branch head" (§3a): (patch) now "the newest verified release (or, on the main channel, the branch head)". §1b: commit is the release tag's commit by default, and best-effort only on main.
  • LIMITS §1a module.json / INSTALL_PATH_RE: (patch) replaced with pharn-install.json and the backstop isPharnOwnedPath + safeJoin + destination symlink walk.
  • LIMITS §1a only .claude/: (patch) now pharn/ and .claude/.
  • LIMITS §1c modules[] / installedSkills[]: (patch) now archetypes / capabilities. "module X" becomes "capability X".
  • LIMITS §1d orphan "reports nothing": covered by C4.2's patch-core-175.py, which rewrites that exact sentence. This patch leaves it alone so the two cannot conflict. It also leaves the C4.2-owned "update never deletes" sentence (LIMITS.md:72) alone.
  • roadmap: no pharn uninstall row: added.
  • roadmap: lock row: now names uninstall.
  • roadmap: backup row: now names init, add, remove and uninstall.
  • roadmap: "Interactive-only init/update": rewritten. Every prompt exits 1 off a TTY, update --yes/uninstall --yes skip the confirm, and init --yes keeps its own row.
  • roadmap: update row ignores channels, no --ref row: the update row follows the recorded channel, and a --ref latest|main row was added.
  • Orphans row: left for C4.2 as instructed.
  • file.ts:line citations become module/function names: (patch) THREAT-MODEL §4c (decideFileAction rows, diffInstalledCapabilities, readDiskState) and LIMITS §1d (mergeCapabilities, deleteCapabilityDir, pruneCapabilityRecords). src/commands/update.ts:452 goes in C4.2's patch. Once both patches are applied, none of the four files has a line citation.

Found while checking every citation (same files)

  • SECURITY: the capability index comes from pharn-install.json and no longer from frontmatter. Its allowlists live in src/lib/upstream-manifest.ts, not capability-index.ts. The fail-closed "stamp check" became the recorded-hash check, because the stamp never gates anything. A record key becomes a path only for the orphan read and the uninstall delete.
  • THREAT-MODEL §3.1: the config no longer carries modules, and pharn never writes seam.
  • LIMITS §1d: "There is no manifest" now reads "no manifest of the pinned install". The expected set comes from the fresh clone's pharn-install.json.
  • LIMITS §3e: the quoted Capability subtree "…" is missing message no longer exists. A structural break is now a pharn-install.json this CLI cannot read (readUpstreamManifest). Only an unknown applies token is tolerated and reported.

Verification

  • npm run lint:md: 0 issues, run on this branch and on both patched files.
  • Every src/... path cited in the four files exists. Every backticked identifier is in src/, except the historical TAR_ENTRY_INVALID.
  • No test or workflow pins THREAT-MODEL.md or LIMITS.md content. prettier covers only TS. The root docs are covered by lint:md and by the protect-trusted-paths hook.

🤖 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 26 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 3e28c8b and 8c3fc40.

Files selected for processing: 4

  • LIMITS.md
  • SECURITY.md
  • THREAT-MODEL.md
  • docs/roadmap.md
  • 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 and others added 2 commits November 17, 2026 13:41
…ut, uninstall (C4.4, CORE-177)

SECURITY.md: the verified release is the default channel and `main` the
opt-in; everything installs under pharn/ and .claude/ (pharn/.lock,
pharn/.backup/); the capability index comes from pharn-install.json, not
frontmatter; every fetch is fetchCapped with a withDeadline hard deadline;
a record key becomes a path only for orphan reads and uninstall.

docs/roadmap.md: add the `pharn uninstall` and `--ref` rows; the lock and
backup rows name uninstall (and init); the TTY row matches init/update/
uninstall --yes; the update row follows the recorded channel.

THREAT-MODEL.md and LIMITS.md follow via the human-applied patch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…line, 24.2 floor (C4.4, CORE-177)

THREAT-MODEL.md: the verified release is the default channel; every fetch
is fetchCapped with the withDeadline hard deadline; the proxy text follows
the 24.2.0 floor; the table names the release resolve; §3.1 drops
`modules`; §4c cites functions instead of line numbers.

LIMITS.md: §1a pharn-install.json + isPharnOwnedPath, files in pharn/ and
.claude/; §1b/§3a the release resolve is the default; §1c archetypes and
capabilities; §1d names instead of line numbers; §3a the 24.2.0 floor's
proxy opt-in; §3e the structural break is an unreadable pharn-install.json.

Applied by a maintainer from the reviewed patch script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@PrzemekGalarowicz
PrzemekGalarowicz force-pushed the przemek/core-177-guarantee-docs branch from 5ed80ef to 76a1814 Compare November 17, 2026 12:42
@PrzemekGalarowicz
PrzemekGalarowicz merged commit 807edc7 into main Nov 17, 2026
15 checks passed
@PrzemekGalarowicz
PrzemekGalarowicz deleted the przemek/core-177-guarantee-docs 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