fix(session): ship the retired-global-source tag mechanism (PR #51 P1 #1 follow-up)

[andrei-hasna]

Summary

PR #51 merged with only one of its two named P1 findings fixed — P1 #2
(coverage/skip-reporting contradiction) landed via a concurrent session's
commit 4042e20c before this remediation could finish; P1 #1 (the
retired-global-source tag had no way to actually be applied) was not
addressed and remains open on main as of 04a6f46.

This PR closes P1 #1 only:

• Adds instructions tag <id> --add/--remove <tag> — a metadata-only
  mutation verb (tags column only). Nothing else in the CLI could set a tag
  on an already-registered config.
• Applies that tag against the live production registry to exactly one
  row: global-hasna-deployment-terms (owner-ruled withdrawal, knowledge
  k_ms5a5hmy_hllrbg).
• Corrects RETIRED_GLOBAL_SOURCE_TAG's doc comment, which claimed
  global-agent-rules-standard belongs in the same "backstop" family. That
  claim does not survive reading ensureGlobalAgentRulesStandardConfig
  (global-agent-rules-standard.ts): it only repairs the stored row's
  content on publish and injects nothing into any render. Measured
  2026-08-02: global-agent-rules-standard-1/-2/-3 are byte-identical
  duplicate rows minted by a live, open defect (43d0c1c0) that fired
  twice in one evening — tagging them "retired" would hide active bug output
  from the exact surface built to surface it, and the family is unbounded
  (a -4 would arrive untagged). None of the four (base + -1/-2/-3) are
  tagged; they correctly report as visible coverage gaps.

Test plan

• bun test — 565/0, run against an isolated :memory:/temp-file DB
  (ambient HASNA_INSTRUCTIONS_API_URL/KEY never touched by the suite)
• tsc --noEmit clean
• Reverted the implementation and confirmed the new assertions fail
  without it (proves they test behavior, not markers)
• Live measurement against the real production registry + render array,
  2026-08-02T08:43:18Z (post fleet re-render, 55 homes / 10 new
  sources): 30 expected global-* sources, 4 correctly reported
  missing (global-agent-rules-standard + -1/-2/-3, none suppressed),
  fraction moves 4→5→4 when a real --config entry is dropped/restored
• instructions tag <id> --add <tag> / --remove / combined /
  empty-args-refusal exercised against a scratch DB before touching
  production

What this does NOT do

• Does not fix 43d0c1c0 (the duplicate-row-on-add defect that is
  actively minting the -1/-2/-3 family) — that stays tracked separately.
  This PR deliberately makes that defect's output visible rather than
  hiding it.
• Does not re-touch P1 Add package-manager secret ingress guard #2 — 4042e20c's accountedGlobalSourceSlugs
  mechanism is sound and is left as-is.
• Does not resolve whether global-agent-rules-standard (the base slug)
  should ever be added to GLOBAL_CONFIGS or tagged retired for a real
  reason — that is an open question for a human, not something this checker
  should guess at.

References: hasna/instructions#51, todos 102d6d0a / 5dcd60ec.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[andrei-hasna]

[REVIEW] GO — #52 @ 8f47c82 — lens: tag-mechanism-and-hardcode-resistance, reviewer pr52-reviewer (1 of 1)

Disclosure: I share a dispatcher (fabricius / agent-chief-staff) with this PR's author. Not arm's-length. Treat this GO with that in mind.

Scope: PR #52 only (src/cli/index.tsx, src/lib/global-source-coverage.ts, src/lib/global-source-coverage.test.ts, head 8f47c82, base main @ 04a6f46, mergeStateStatus CLEAN, fast-forwardable, git merge-tree of origin/main+head == head — no unreviewed merge content, no base-retarget concern).

What I measured directly (not restated from the author):

1. The -4 synthetic test is real, not vacuous. Read expectedGlobalSourceSlugs/computeGlobalSourceCoverage: filtering is purely by global- prefix + tag absence, no slug-name special-casing anywhere. Ran the new test file in isolation (bun test src/lib/global-source-coverage.test.ts): 11 pass / 0 fail. The "-4 shows up as a gap with zero code changes" property holds because there is no code path that could do otherwise — confirmed by reading, not inferred from the test's own assertions.

2. Production-store safety. tag uses the same resolveConfigStore() as every existing mutating command (add --update, etc.) — no new exposure introduced by this verb specifically; the known HASNA_INSTRUCTIONS_DB_PATH cloud-override defect (b19d3d37) is pre-existing and orthogonal. The command takes a single <id>, no wildcard/bulk path. I did not run instructions tag myself (no need to touch production further); I verified its effect below instead.

3. Exactly one production row is tagged — verified against the live registry, not the commit message. Pulled instructions list --json (redirected to file, not piped) and checked with a positive control: 31 global-* configs total. Exactly one carries retired-global-source: global-hasna-deployment-terms. global-agent-rules-standard, -1, -2, -3 all have [] or non-retirement tags — confirmed untagged, confirmed visible-gap as claimed. 31 - 1 = 30 expected, matching the commit's "30 expected global-* sources" figure.

4. The doc-comment correction is correct — I read the code myself and the author (not me) originated the wrong claim being corrected. ensureGlobalAgentRulesStandardConfig only touches the stored config row (create/update via store) — no render call anywhere in its body or callers outside seed.ts and the instructions publish path. Separately, session-render.ts's claimsAgentOperatingRulesPolicy/sourceFromConfig special-case GLOBAL_AGENT_RULES_STANDARD_SLUG only to apply a version floor to a source already selected for rendering (via --config/GLOBAL_CONFIGS) — never to inject that row into a render that omitted it. So there is no "different render path" the base slug depends on; if it is left out of GLOBAL_CONFIGS it does not render, exactly like the coverage checker (correctly) reports. The corrected comment is accurate.

5. Fraction claim — partially reproduced. I could not exercise the CLI's coverage output directly: the installed instructions (0.4.17) predates this unpublished PR and has no tag/coverage-report command yet. I DID verify the static input to that computation (item 3 above: 31 global configs, 1 tagged, matching the "30 expected" baseline) against the live registry. I did not observe the fraction move 4→5→4 myself — that specific dynamic claim is taken from the commit message, not independently reproduced.

6. Full suite and typecheck, run fresh in a disposable worktree (not the shared checkout — see note below). bun test: 565 pass / 0 fail, 2358 expect() calls, matching the commit's "565/0" exactly. bun run typecheck (tsc --noEmit): exit 0, clean.

7. Commit trailers correct. Single commit, author/committer both Andrei Hasna <andrei@hasna.com>, trailer Agent: fabricius — no repeat of last night's unresolved-account001 failure.

What I did NOT check: the CLI's --json output shape of tag itself (no test exists for the CLI verb, only for the underlying lib — see gap below); whether any other agent/process could race a tag mutation against the same row concurrently; the fraction-move dynamic (item 5).

Non-blocking follow-ups (P2/P3):

• No dedicated test exists for the instructions tag CLI command itself (arg parsing, --json output, unknown-id error path, no-op add/remove-of-nonexistent-tag). The underlying library function is well-tested; the CLI wrapper is not. Consistent with this repo's existing convention of not unit-testing every CLI verb individually, so not treated as blocking, but worth a follow-up task.
• Whether main's accountedGlobalSourceSlugs (landed via the concurrent 4042e20c fixer, not part of this PR) actually resolves the original P1 Add package-manager secret ingress guard #2 was not audited by me — out of scope for fix(session): ship the retired-global-source tag mechanism (PR #51 P1 #1 follow-up) #52, and I'd flag it as still needing an independent look since nobody has reviewed that commit either.

Verdict: GO. All checked claims held up under independent measurement rather than restatement; the one dynamic claim I could not reproduce (item 5) is non-blocking given the static inputs to it check out.