feat(engine): PIN-DEAD — the one command a stranger runs

Reported by org-ops (census 08, R1) and re-measured here against the FORGE
rather than taken on their word: 3 install pins in the org, 1 dead.
`llm-ingestion-pipeline-security` pins ITSELF to `@v0.7.0`; that tag does not
exist, newest is v0.6.1. Anyone copying the single install command out of that
README gets a hard pip failure.

ERROR, not WARN: a dead documentation link costs a stranger a 404, a dead pin
costs them the install.

Not a duplicate of two checks it sits near. `LINK-DEAD` asks whether the repo
exists; `VERSION-TAG` reads the MANIFEST and asks whether that version was ever
tagged. All three land on guard today only because the same wrong number got
written in three places — a README pinning a bad ref in a repo with a correct
manifest is invisible to both.

Resolved against the forge, never the clone: a local tag can exist without
having been pushed, which portfolio-optimiser demonstrates directly. That uses
this session's decided acquisition model — `git ls-remote --tags` on the
register-derived https URL, anonymous, no API budget, and only for the repos a
README actually pins (nothing at all for the 19 that pin none).

A pin at a branch or a sha is a `byDesign` skip. `ls-remote --tags` cannot
answer it, and a loose pin is a different finding from a dead one.

The corpus sweep found a defect a unit test had not: offline, guard emitted the
SKIP *and* an OK reading "1 install pin(s) resolve against the forge" — a pass
asserted for a pin nothing had read. SKIP is never a pass. The OK now counts
only what was actually verified ("N of M"), and two tests pin it.

Measured before and after across all 21 clones: purely additive, no existing
finding moved. 19 repos emit PINS-NONE (OK — the check read the whole README
and found no subject), 2 emit real pins. Online, okf's 2 pins resolve and
guard's 1 does not: exactly one new ERROR org-wide, matching org-ops.

196 tests (was 187).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015AkHEqTSr1k3HbeiHu1ggW

scripts/repo-standard-check.test.mjs

@@ -22,6 +22,8 @@ import {
   checkHeadings,
   checkBadges,
   checkTagIntegrity,
+  checkInstallPins,
+  extractInstallPins,
   checkReadmeLanguage,
   checkBoilerplate,
   checkLicenseClaim,
@@ -927,6 +929,98 @@ test('newest is the highest version, not the last element of an unsorted list',
   assert.equal(f.some((x) => x.code === 'TAG-ANNOTATED-HISTORY'), true);
 });
 
+// ---------------------------------------------------------------- dead pins
+//
+// Reported by org-ops (census 08) and re-measured here against the FORGE, not
+// the clones: 3 pins in the org, 1 dead —
+// `llm-ingestion-pipeline-security` pins ITSELF to `@v0.7.0`, which does not
+// exist (newest is v0.6.1). ERROR, not WARN: a dead documentation link costs a
+// stranger a 404, a dead pin costs them the one install command that was
+// supposed to work.
+const PIN_REG = { org: 'open', forge: 'https://git.fromaitochitta.com' };
+
+test('an install pin is extracted with its repo and ref', () => {
+  const readme = '```bash\npip install "guard @ git+https://git.fromaitochitta.com/open/llm-ingestion-pipeline-security.git@v0.7.0"\n```';
+  const pins = extractInstallPins(readme, PIN_REG);
+  assert.equal(pins.length, 1);
+  assert.equal(pins[0].repo, 'llm-ingestion-pipeline-security');
+  assert.equal(pins[0].ref, 'v0.7.0');
+});
+
+test('a pin whose ref is not a tag on the forge is an ERROR', () => {
+  const readme = 'pip install "g @ git+https://git.fromaitochitta.com/open/guard-repo.git@v0.7.0"';
+  const f = checkInstallPins({ readme, forgeTagsByRepo: { 'guard-repo': ['v0.6.0', 'v0.6.1'] } }, PIN_REG);
+  const hit = f.find((x) => x.code === 'PIN-DEAD');
+  assert.equal(hit.level, 'ERROR');
+  assert.equal(hit.bucket, 'broken');
+  assert.match(hit.msg, /v0\.7\.0/);
+  assert.match(hit.msg, /v0\.6\.1/); // names what DOES exist, so the remedy is obvious
+});
+
+test('a pin whose ref resolves is OK', () => {
+  const readme = 'pip install "g @ git+https://git.fromaitochitta.com/open/guard-repo.git@v0.6.1"';
+  const f = checkInstallPins({ readme, forgeTagsByRepo: { 'guard-repo': ['v0.6.0', 'v0.6.1'] } }, PIN_REG);
+  assert.equal(f.some((x) => x.level === 'ERROR'), false);
+  assert.equal(f.some((x) => x.code === 'PINS'), true);
+});
+
+// `ls-remote --tags` cannot answer a branch or a sha, and a branch pin is a
+// different weakness (an unpinned install), not a dead one. This check can
+// never produce a verdict on it, so the skip is byDesign — nobody has an
+// action that would turn it into one.
+test('a pin at a branch or a sha is a byDesign skip, never a dead pin', () => {
+  const readme = 'pip install "g @ git+https://git.fromaitochitta.com/open/guard-repo.git@main"';
+  const f = checkInstallPins({ readme, forgeTagsByRepo: { 'guard-repo': ['v0.6.1'] } }, PIN_REG);
+  const hit = f.find((x) => x.code === 'PIN-NOT-A-TAG');
+  assert.equal(hit.level, 'SKIP');
+  assert.equal(hit.skip, 'byDesign');
+});
+
+test('offline leaves the pin un-judged, and says so as notRun', () => {
+  const readme = 'pip install "g @ git+https://git.fromaitochitta.com/open/guard-repo.git@v0.7.0"';
+  const f = checkInstallPins({ readme, forgeTagsByRepo: null }, PIN_REG);
+  const hit = f.find((x) => x.code === 'PIN-UNAVAILABLE');
+  assert.equal(hit.level, 'SKIP');
+  assert.equal(hit.skip, 'notRun');
+});
+
+// Caught by the corpus sweep, not by a unit test: offline, guard emitted the
+// SKIP *and* an OK reading "1 install pin(s) resolve against the forge" — a
+// pass asserted for a pin nothing had checked. SKIP is never a pass.
+test('an unverified pin never produces an OK claiming it resolves', () => {
+  const readme = 'pip install "g @ git+https://git.fromaitochitta.com/open/guard-repo.git@v0.7.0"';
+  const f = checkInstallPins({ readme, forgeTagsByRepo: null }, PIN_REG);
+  assert.equal(f.some((x) => x.code === 'PINS'), false);
+  assert.equal(f.some((x) => x.level === 'OK'), false);
+});
+
+test('the OK counts only the pins actually verified', () => {
+  const readme = [
+    'pip install "a @ git+https://git.fromaitochitta.com/open/alpha.git@v1.0.0"',
+    'pip install "b @ git+https://git.fromaitochitta.com/open/beta.git@v2.0.0"',
+  ].join('\n');
+  const f = checkInstallPins({ readme, forgeTagsByRepo: { alpha: ['v1.0.0'] } }, PIN_REG);
+  const ok = f.find((x) => x.code === 'PINS');
+  assert.match(ok.msg, /1 of 2/);
+  assert.equal(f.some((x) => x.code === 'PIN-UNAVAILABLE'), true);
+});
+
+test('a pin at somebody else’s forge is not ours to judge', () => {
+  const readme = 'pip install "x @ git+https://github.com/other/thing.git@v9.9.9"';
+  const f = checkInstallPins({ readme, forgeTagsByRepo: {} }, PIN_REG);
+  assert.equal(f.some((x) => x.code === 'PIN-DEAD'), false);
+  assert.equal(extractInstallPins(readme, PIN_REG).length, 0);
+});
+
+// The VERSION-NONE shape: the check ran, read the whole README, and found no
+// pin. Nothing here can be wrong — that is a verdict, not an absent one.
+test('a README with no pins has nothing to judge — OK, not SKIP', () => {
+  const f = checkInstallPins({ readme: '# hello\n\nno install pins here', forgeTagsByRepo: {} }, PIN_REG);
+  assert.equal(f.length, 1);
+  assert.equal(f[0].level, 'OK');
+  assert.equal(f[0].code, 'PINS-NONE');
+});
+
 // ------------------------------------------------------------ badge honesty
 
 test('a static badge asserting test or build status is a finding', () => {