Require the Claude Code link in the installer's ok state for a global skill - #1024

… (F3 of #1024)

Where an add is about to run over an existing folder whose SKILL.md is the pinned one (an unlocked folder, or one locked at the pin whose Claude link is missing), the folder must hold SKILL.md alone or be the pinned tree: the git tree SHA that scripts/skills_status.py already computes, with the regenerable runtime-artifact directories left out, equals the manifest's tree_sha. Anything else is local-modified, refused unless --force, for the global canonical folder, a Claude-Code-only copy and a project folder. Measured with the real pinned CLI: a file added to an unlocked gh-fix-ci folder was deleted at main 83cec12 and survives now. The canonical-link rule stays literal; an upgrade over an older lock and an ok install are not covered. Also the --force help text (P3-2), the Codex-only scope of the link rule in the lifecycle record (P3-3) and a missing space in a test (P3-5).

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

… parent aliases

install_skills.py refuses a link at the canonical skill path and accepts a link on a parent folder (createSymlink L240-250); scripts/skills_status.py followed the first and failed the second. It now reports canonical_link for a link at the skill path (the reverse alias of #1024 included) and accepts a real folder that a parent link makes the canonical folder itself (kind parent_link), for a global entry only: the Claude-Code-only copy check is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

… (F3 of #1024)

Where an add is about to run over an existing folder whose SKILL.md is the pinned one (an unlocked folder, or one locked at the pin whose Claude link is missing), the folder must hold SKILL.md alone or be the pinned tree: the git tree SHA that scripts/skills_status.py already computes, with the regenerable runtime-artifact directories left out, equals the manifest's tree_sha. Anything else is local-modified, refused unless --force, for the global canonical folder, a Claude-Code-only copy and a project folder. Measured with the real pinned CLI: a file added to an unlocked gh-fix-ci folder was deleted at main 83cec12 and survives now. The canonical-link rule stays literal; an upgrade over an older lock and an ok install are not covered. Also the --force help text (P3-2), the Codex-only scope of the link rule in the lifecycle record (P3-3) and a missing space in a test (P3-5).

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

… parent aliases

install_skills.py refuses a link at the canonical skill path and accepts a link on a parent folder (createSymlink L240-250); scripts/skills_status.py followed the first and failed the second. It now reports canonical_link for a link at the skill path (the reverse alias of #1024 included) and accepts a real folder that a parent link makes the canonical folder itself (kind parent_link), for a global entry only: the Claude-Code-only copy check is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

…(F3), and align the status check (#1035)

* Do not let the skills add delete content the pinned CLI did not write (F3 of #1024)

Where an add is about to run over an existing folder whose SKILL.md is the pinned one (an unlocked folder, or one locked at the pin whose Claude link is missing), the folder must hold SKILL.md alone or be the pinned tree: the git tree SHA that scripts/skills_status.py already computes, with the regenerable runtime-artifact directories left out, equals the manifest's tree_sha. Anything else is local-modified, refused unless --force, for the global canonical folder, a Claude-Code-only copy and a project folder. Measured with the real pinned CLI: a file added to an unlocked gh-fix-ci folder was deleted at main 83cec12 and survives now. The canonical-link rule stays literal; an upgrade over an older lock and an ok install are not covered. Also the --force help text (P3-2), the Codex-only scope of the link rule in the lifecycle record (P3-3) and a missing space in a test (P3-5).

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Make the status check agree with the installer on canonical links and parent aliases

install_skills.py refuses a link at the canonical skill path and accepts a link on a parent folder (createSymlink L240-250); scripts/skills_status.py followed the first and failed the second. It now reports canonical_link for a link at the skill path (the reverse alias of #1024 included) and accepts a real folder that a parent link makes the canonical folder itself (kind parent_link), for a global entry only: the Claude-Code-only copy check is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Register the F3 files in the evidence manifest

Last commit of the change: the rows of every file it adds or changes, at their final bytes.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Refuse a regular file named like a runtime directory, and a repairing add over local work in a locked project; keep the push gate's read inventory unchanged

The first reads of #1035 (Astra at 295ada5 and the four open Codex review threads) found two ways the guard still lost local work and one regression. One commit:

- A regular file or a link named `.venv`, `node_modules`, `__pycache__` and the like was taken for a regenerable directory (the name was excluded before the entry's type was looked at),
  and the add deleted it. git_tree_sha now skips such a name only for a real directory and does not follow a link. The SKILL.md-alone shortcut, which had the same flaw and also followed a
  SKILL.md link, is removed: a lone SKILL.md is hashed like any other folder.
- A project locked at the pin whose Claude target is missing returned `install` before the content check, so the repairing add deleted local files. The check now runs before that repair in
  a project as it does in the global scope.
- The shortcut's os.listdir was a sixth unclassified read site of the push gate's monitoring baseline (342 -> 343; tests.test_runtime_worker_openhands_push_gate failed 1 of 125 and
  repeated). With the shortcut gone the installer has its five reads again: 125 of 125 pass at this head.
- The status check rejected a canonical-leaf link for a Codex-only entry that the installer accepts; both now apply the rule to entries installed for Claude Code only. The moved link to
  budget_report in the 2026-10-10 record points at its current line.

tests/test_install_skills.py::PinnedCliForeignContentTests repeats the two measurements offline with the pinned skills 1.7.0 CLI where it is installed (a local source folder, a scratch
home and project, telemetry off): the classifier must say local-modified before any add, and the same add on a copy must delete the entry (the control). Where the CLI is not installed it
is skipped; the fake-CLI tests cover the same states. The record and the lifecycle are updated; the evidence rows are re-registered at their final bytes.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Compare the whole folder before any add over a locked skill, fail closed on entries a git tree cannot hold, and judge runtime-named files the same way in the status check

Fix wave 2 of #1035, on 9a77a96: the second GPT read (blockers 1 and 2, follow-up 3) and the open Codex thread (P2, "Fail closed on entries omitted from the tree hash").

- A lock at the requested pin plus an existing canonical folder is not an upgrade, and the add recreates the folder from nothing (vercel-labs/skills@7407f389 src/installer.ts L195, called at L389). classify_skill
  returned "install" when SKILL.md was not the pinned one, before the content check ran, so an edited SKILL.md plus a local file were deleted without --force. Now, when the lock names the pin (a project:
  source, ref, path and the pinned tree; a global entry: skillFolderHash), the folder is compared whatever made the add necessary (a missing Claude target, a missing link, an edited or missing SKILL.md); a
  folder that is gone is a clean repair; a lock that names another tree stays an upgrade over an older pin (the documented boundary).
- git_tree_sha(strict=True) raises UnrepresentedEntry for an entry a git tree cannot hold (an empty directory, a FIFO, a socket, a device), which the add deletes all the same; the installer refuses it with a
  fixed text and never prints a tree for it. The status check stays a git-tree comparison.
- check_folder_tree skipped runtime-artifact names by name at every level; it now skips only real directories (skip_dirs_only), as the installer does, so a regular file or a link named .venv is drift.
- The two live line locators in the daily-record decision now point at budget_report (571) and claude_skills_dir (260).

Fail-first: the final tests of tests.test_install_skills and tests.test_skills_status (194) give 23 failures and 6 errors against the implementation of 9a77a96 (9 tests: global and project edited-SKILL.md
through the full installer path, the real pinned CLI in both, unrepresented entries, strict mode, the status check against the installer) and pass here; 20 of 20 installer mutants and 13 of 13 status mutants killed.
The evidence rows of the changed files are updated.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Read a lock as naming an older pin only when it names another revision, and compare the folder in every other lock shape

Fix wave 3 of #1035, on 5ace90c: Astra's delta read (~/.cache/ns2604-gpt-reads/fix2-pr1035-5ace90c12/VERDICT.md: one P1, one P2) and the command center's Claude full read (pr1035-claude-read-5ace90c1.md: PASS_WITH_P3, no P1; F3 here, F4 and F5 are claims of the PR body).

- P1 (Astra): classify_skill returned "install" before the content check when a project lock entry lacked the optional `skillPath` (a lock written before the field existed), or its `computedHash` was not
  64 hex digits, so the add recreated the folder from nothing (vercel-labs/skills@7407f389 src/installer.ts L195, called at L389) and deleted local work without --force. The pinned CLI makes these
  fields optional or does not need them whole: src/local-lock.ts L16-L37 (`ref?` and `skillPath?` are "optional for backward compatibility with lock files written before this field existed" and
  "omitted for non-repo sources"; `computedHash` is the CLI's own hash of the folder, not a revision), and readLocalLock and readSkillLock return an empty lock for a file that is too old or does not
  parse (src/local-lock.ts L83-L98; src/skill-lock.ts L89-L101). An entry that lacks them says nothing about which revision wrote the folder. The same early return took a project entry without `ref`, one that names
  another source and the entry the CLI writes for a local folder (`sourceType: local`, no `ref`, no `skillPath`; measured with the real CLI), and a global entry whose `skillFolderHash` is missing, empty
  or not text.
  The rule: only an entry that positively names another revision of the manifest's source (a project `ref` that is non-empty text and is not the pin's; a global `skillFolderHash` that is non-empty text
  and is not the pin's tree) is an upgrade over an older pin and runs as before. Every other entry is read like no lock: the folder must be the pinned tree, a folder that is gone is a clean repair, and
  `ok` needs the whole entry (source, type, `ref`, `skillPath`, a 64-digit `computedHash`; the global tree) with the pinned SKILL.md and the link.
- F3 (command center): the module docstring (printed by --help) now gives the scope of the rule as it is: the edited SKILL.md, the lock shapes, the entries a git tree cannot hold.
- P2 (Astra), the earlier review's locator premise: the previous read found the two live line locators of the daily-record decision "two lines short" (250 and 558 against 252 and 560). That was a false
  positive: lines are counted by LF (editors, grep -n, GitHub), and str.splitlines() also breaks at U+2028 and U+2029, one of each in skills_status.py, which shifted its count by two. The links of
  5ace90c (260 and 571) are updates for this change's own line movement and stay.

Fail-first: the tests of tests.test_install_skills and tests.test_skills_status (202) give FAILED (failures=34) in 5 tests on 5ace90c (the global lock shapes, the project lock shapes for both agents,
and the real pinned CLI for a lock without skillPath, for the lock the CLI writes for a local folder and for a global lock without a tree) and pass here. Mutants: 15 of the new lock logic, 11 retained of the
installer and 13 of the status check, all killed; nine earlier mutants of branches that this commit rewrites are replaced by the 15. Not taken, listed in the PR body: F1 (a project repair is refused,
fail-closed, for a folder whose pinned tree holds a symlink or metadata.json, which the CLI's copy dereferences or leaves out), F2, F6.
The evidence rows of the changed files are updated.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Read a lock from the upstream definition of what the pinned CLI writes: an entry names an older pin only as a git tree id or a commit id of the manifest's source

Fix wave 4 of #1035, on 453ac68, by the command center's adjudication (adjudication-pr1035-453ac683-20261012.md: the lock-shape class recurred, so the fix starts from the upstream definition, enumerates every
lock-entry form the pinned CLI writes or leaves, project and global, builds the test table from it and fails closed for anything outside it). Inputs: Astra's delta read (~/.cache/ns2604-gpt-reads/fix3-pr1035-453ac6834/VERDICT.md:
one P1, one P2, seven P3) and the command center's Claude delta (pr1035-claude-micro-453ac683.md: B1 at P1, one P2, five P3).

- P1, both files: classify_skill returned "install" before the content check for a global entry whose `skillFolderHash` is any non-empty text that is not the pin's tree (Astra: "not-a-tree", 39 hex digits, one
  space), for the CLI's own sha256 digest of the folder (the CC: what src/add.ts L2108-L2111 writes where the GitHub tree lookup returns nothing, and for every gitlab, git and local source), and for an entry
  of another source or type (src/add.ts L2114-L2122 records `source` and `sourceType` for every global install); the add then recreated the folder (src/installer.ts L195, called at L389) and deleted local
  work without --force. Reproduced with the real pinned CLI for a generic git source, global and project (the entry it writes holds the digest, a URL and no `ref`).
- The reading is now one function, lock_reading, built from the table: an entry names another revision only through a field the CLI writes as one, in that form (a global `skillFolderHash` that is a git tree id,
  40 hex digits matched case-insensitively as src/update.ts L638 does; a project `ref` that is a full commit id), and only for the manifest's GitHub source; a tree id equal to the pin's is a content address and
  reads "same" whatever source wrote it. Everything else is "unidentified" and the folder is compared like an unlocked one: a digest, a URL source, a branch, a tag or an abbreviated id as `ref` (src/local-lock.ts
  L19-L20: what the user typed), an empty, missing or malformed field. A lock file the CLI reads as empty (no numeric `version`, a version below 3 global or 1 project, no `skills` table; for a project any
  entry that is not an object: src/skill-lock.ts L89-L101, src/local-lock.ts L83-L98) holds no entry (lock_skills). `ok` needs the whole entry and the pinned SKILL.md and link.
- The table: 53 entry forms (26 global, 27 project) and 20 lock-file forms, each with its upstream citation, in the "Lock entries" section of the decision record and in LOCK_ENTRY_TABLE and LOCK_FILE_TABLE of
  tests.test_install_skills, run for the global scope and for a project under both agents in three folder states (pristine, a local file beside the pinned ones, folder gone), through the classifier and through the
  full installer path with the fake CLI, plus the real pinned CLI for the generic git source.
- The command center's P2 (body line 107, F3 listed as open), P3-1 (the test count), P3-2 (a ref that is a branch or a tag is compared: it can name the pin's own commit), P3-3 (the lock version rule),
  P3-4 (the fixtures write the numeric `version` and the source the CLI writes), P3-5 (the quotation belongs to `skillPath`; the pinned CLI writes no global lock for a local folder): fixed here or in the body.
  F1 (a project repair is refused for a folder whose pinned tree holds a symlink or metadata.json), F2, F6 and the P3s of both reads stay in the PR body's Follow-ups.

Fail-first: tests.test_install_skills and tests.test_skills_status (208 tests) give FAILED (failures=41, errors=85) in 5 tests on 453ac68 (the lock-entry table, the lock-file table, lock_skills, the installer
path and the real-CLI generic git source) and pass here. Mutants: 28 of the lock reading (the version rule and its minimums, the boolean and text versions, the null-entry rule, what counts as an id, its case and length, the pin comparison, the source and its type, the project and global field, every branch that sends an entry that identifies nothing to an install or to ok, the whole-entry test, the tree oracle, a gone folder), 11 retained of the installer and 13 of the status check: all killed (survivors: none); nine earlier installer mutants named branches of classify_skill that this commit rewrites, and the 28 replace them.
The evidence rows of the changed files are updated.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Read a lock as the pinned reader reads it in every rejection it has: JSON constants and a local source that is not text

Fix wave 5 of #1035 on 5f23fc3 (23e2dcb rebased onto main 2f59d74), released by the command center. Inputs: Astra's delta read of 23e2dcb (GPT-VERDICT-23e2dcbe9.md, 30,112 bytes, sha256 2ec782f8: three P1,
one P2 carried under the scope lock, seven P3) and the command center's tests-only Claude check, which passed.

- P1, global and project: load_lock took the tokens NaN, Infinity and -Infinity, which json.loads accepts and JSON.parse rejects (skills@7407f389 src/skill-lock.ts L85, src/local-lock.ts L80); both pinned readers
  return an empty lock when it throws (L99-L101, L97-L98), so the entry in such a lock excused nothing, but the installer read it as an older pin and let the add recreate the folder over local work. load_lock now
  passes parse_constant=reject_constant (CPython's hook for invalid JSON numbers, Doc/library/json.rst L324-L329 at python/[email protected]): a lock with a constant anywhere is unreadable and the folder is
  compared like an unlocked one. 1e999 is a valid number (both parse it as Infinity) and stays readable.
- P1, project: lock_skills read every entry that is an object, but the pinned reader's loop throws, and its catch returns an empty lock, for a null entry and for a local entry whose source is missing or is not
  text (src/local-lock.ts L90-L98: isAbsolute(entry.source)); another entry of that kind excused the deletion for the managed entry at another commit. lock_skills now reads such a project lock as empty, for the
  managed entry or any other. The source description is corrected: the reader does not throw on an entry that is a string, a number, true or a list (measured by executing the pinned reader bodies on Node
  24.21.0, reader-measure-20261012.txt); this installer still reads such a lock as empty, which is stricter than the reader and is now documented as such.
- P1, privacy: the Git fixture of the native generic-source test gave author and committer an email-shaped literal; both are now the placeholder no-address, which is not an email (git takes it).
- The fake CLI of the tests read a lock more leniently than the pinned readers, so a damaged lock survived its own add; its load_lock now mirrors them (constants, version, falsy skills, the project null and
  local-source rules), which lets the clean-install controls run on the complete installer path.

Tests: LOCK_FILE_TABLE gained 19 forms (GL11-GL16, PL10-PL22; 39 in all) and LOCK_FILE_STRICTER_TABLE holds the four forms the reader keeps and this installer does not; every form runs through the classifier and
through the whole installer path (refused with no add and the folder untouched where local work sits; installed where nothing is at risk), plus a unit test of load_lock on text, cases of lock_skills, and two
controls with the real pinned CLI (the native add deletes the file the classifier protects).

Fail-first: tests.test_install_skills and tests.test_skills_status (212 tests) give FAILED (failures=76, errors=1) in 6 tests on 5f23fc3 and pass here (136 + 76). 10 mutants of the new reader rules and 4 of the
fake CLI's reader killed. Astra's P2 and the P3s go to the PR body's Follow-ups. The evidence rows of the changed files are updated.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>