chore: credstore dependency surface + cli-common self-conformance (standards-review level 2)

[rianjs]

Context

Level 2 of the standards review audited the shared code against the docs it implements (credstore vs working-with-secrets.md; statedir/statedirtest/cache vs working-with-state.md). Zero contract violations — the Linux fail-closed classification, SetBundle snapshot/rollback, redaction suite, resolver no-create split, 8-var hermetic helper, and tier-1 cache surface are all implemented and tested as specified. The remaining work is one substantive dependency finding plus this repo's own conformance, with downstream consumer impacts mapped below. Depends on #54 for the doc-side changes (library profile, divergence rewording).

Current consumer pins (all affected by anything tagged here): google-readonly, newrelic-cli, slack-chat-api, atlassian-cli (shared + cfl + jtk) @ v0.2.2; codereview-cli @ v0.3.0.

1. credstore dependency surface (substantive)

byteness/keyring's root package imports its 1Password openers unconditionally, so the chain

credstore → byteness/keyring → onepassword-sdk-go (pre-1.0) → extism/go-sdk → wazero

is in the package import graph, not just the module graph. Measured on this repo: go list -deps ./credstore includes 63 packages from these trees — tetratelabs/wazero (34 packages — a full WASM runtime), uber/jaeger-client-go (19 — archived upstream), OTel protos, dylibso/observe-sdk, both 1Password SDKs — compiled into a credential library and therefore into every consumer binary.

working-with-secrets.md §1.10 already (correctly) refuses to expose the op backends precisely because the SDK is pre-1.0 — but the dependency still rides along: binary size, vuln/audit surface, and dependabot noise in every consumer's go.sum.

Work:

• Quantify: binary-size delta for a consumer binary with/without the trees; govulncheck against a consumer binary; check whether the linker actually dead-code-eliminates wazero/jaeger (init-heavy packages often survive DCE).
• Fix path, in preference order: (a) change byteness/keyring (we control the fork) to gate the op/op-connect/op-desktop openers behind build tags or split them into a submodule, so importers that never request those backends don't compile them; (b) if (a) is impractical, accept and document the trade-off in working-with-secrets.md §1.10.
• If (a): repin byteness/keyring in cli-common, then tag and ride the consumer repin train (item 4).

2. cli-common mechanical conformance (blocked on #54 item 5 — the library profile)

• .github/workflows/ci.yml: replace both hardcoded go-version: '1.26' with go-version-file: go.mod (ci.md §3 — this repo currently exhibits the exact drift the rule bans).
• Makefile: check: tidy lint test build (today check omits build while CI builds, so a green local check does not predict a green CI run — violates repo-layout.md §4's own contract).
• Add AGENTS.md + CLAUDE.md as thin peer indexes per agent-implementation.md §2 (each points to docs/development.md and docs/README.md; they MUST NOT point at each other; since this repo is the standards home, the source-of-truth links are local).
• Add docs/development.md: package map (credstore / statedir / statedirtest / cache with the doc sections each implements), make check, hermetic-test rules (in-memory backend, statedirtest.Hermetic, not t.Parallel-safe), and the manual-tag / release-train policy.
• Decide: keep the monolithic build-test CI job (remains a catalogued ci.md §8 divergence) or split build/test jobs while in there.

3. Color verification pass (downstream of #54 item 3)

• Verify each CLI (jtk, cfl, gro, nrq, slck, sfdc) does not force color onto non-TTY output. fatih/color and lipgloss auto-disable by default, so this should be a no-op confirmation unless a CLI sets color.NoColor = false or equivalent. Record the result in output-and-rendering.md §10. (gro's missing root --no-color flag is already a catalogued §10 divergence — out of scope here.)

4. Tag + repin train

• After docs: resolve standards-family contradictions, gaps, and stale references (review decisions applied) #54 and the items above land: cut the next semver tag per the working-with-state.md §6 release-train guardrail. The standards docs co-version with the code, so consumers pinned at v0.2.2 read stale standards until repinned — repin consumers opportunistically (no API change expected unless 1(a) alters credstore's surface, which it should not).

[rianjs]

Plan: cli-common#55 — dependency-surface documentation + self-conformance (level 2)

Branch: chore/55-conformance-and-dep-surface. One PR in cli-common. Maintainer decisions during planning (2026-06-11): document-only for the keyring dependency finding — the upstream build-tag PR is committed separately in #57 (we have read-only access to ByteNess/keyring; the issue's "we control the fork" was wrong). Depends on #54 (merged as PR #56): the library profile (repo-layout.md §2.1) this PR conforms to, and the §10 color-divergence bullet this PR updates.

Quantification already done (pre-plan investigation, posted to the issue)

• go list -deps ./credstore: 63 packages from the wazero/jaeger/1Password/OTel trees.
• Real consumer binary (slck): 5,393 surviving symbols — no dead-code elimination (init-registered openers).
• go tool nm -size: ~10.6 MB attributable symbol bytes.
• byteness/keyring v1.9.3 source: the five op*.go files are the only SDK importers, already build-constraint-gated (!freebsd) — upstream tag PR is small and precedented (design in chore: upstream opt-out build tag to ByteNess/keyring for the 1Password backends #57).
• Access check: ByteNess/keyring is pull-only for us.

Work items

W1. Document the dependency trade-off (docs/working-with-secrets.md §1.10)

Extend the existing "what credstore exposes" paragraph: even though the op backends are not exposed, byteness/keyring compiles its 1Password openers into every consumer (quantified numbers above, dated); the accepted interim posture is documented-cost; the opt-out-tag remediation is tracked in cli-common#57. Keep it to one tight paragraph — §1.10 already carries the "deliberately not exposed" rationale.

• Check: §1.10 names the cost (MB, package count), the date measured, and points at chore: upstream opt-out build tag to ByteNess/keyring for the 1Password backends #57. No other doc text promises the dependency is free.

W2. Post quantification + access-correction comment on #55

Issue body says "we control the fork" — correct the record in a comment with the measured numbers and the #57 pointer. (govulncheck run included if it completes cleanly; it analyzes reachable code, so its findings are informative for the "what does the tag actually buy" question.)

• Check: comment posted; issue checklist items for item 1 addressed or re-routed to chore: upstream opt-out build tag to ByteNess/keyring for the 1Password backends #57.

W3. Mechanical conformance (per repo-layout §2.1, landed in #54)

• .github/workflows/ci.yml: both go-version: '1.26' → go-version-file: go.mod (ci.md §3).
• Makefile: check: tidy lint test build.
• AGENTS.md + CLAUDE.md: thin peer indexes per agent-implementation §2 — point first to docs/development.md, then docs/README.md (standards index; source-of-truth links are local because this repo IS the standards home), then shared automation (open-cli-collective/.github). They MUST NOT reference each other. Identical content is acceptable and expected for peers.
• docs/development.md: repo-local facts only — package map (credstore / statedir / statedirtest / cache, each with the doc §§ it implements), make check mirrors CI, hermetic-test rules (memory backend; statedirtest.Hermetic, not t.Parallel-safe; never the dev's real keychain/home), release = manual semver tags under the §2.1 library profile with the working-with-state §6 consumer-matrix gate, exported-API change policy (additive or release train).
• CI job shape: keep the monolithic build-test job — splitting is not required by the §2.1 profile and stays a catalogued ci.md §8 divergence. Surgical scope.
• Check: make check green locally AND the new build step runs; agent-implementation §6 checklist passes against the new entrypoints (peer indexes, no cross-reference, local paths resolve, no copied policy prose).

W4. Color verification pass (downstream of #54's §8 flip)

Read-only audit of the six CLIs in ~/dev (jtk, cfl, gro, nrq, slck, sfdc), broad enough to defend a "verified" claim — not just the expected-library greps:

1. Inventory every color path per CLI: imports/usages of fatih/color, lipgloss, termenv, any other color package, AND raw ANSI escape literals (\x1b[ / \033[ / �) in non-test source — a hand-rolled ANSI writer is exactly what the library-default assumption would miss.
2. For each hit, check for forcing: color.NoColor assignments, lipgloss/termenv renderer or ColorProfile overrides, SetColorProfile, CLICOLOR_FORCE handling, or unconditional escape writes to stdout/stderr.
3. Record evidence: per-CLI repo SHA audited + file:line for every color path found, in the PR description.
   Expected result: no CLI forces color onto non-TTY output. Update the output-and-rendering.md §10 bullet (added in docs: resolve standards-family contradictions, gaps, and stale references (review decisions applied) #54) from "unverified — tracked in chore: credstore dependency surface + cli-common self-conformance (standards-review level 2) #55" to the dated verified result with the audited-SHA list — or catalogue any forcing CLI as a divergence instead.

• Check: §10 bullet states the verified result with date; PR description carries per-CLI SHAs and the color-path inventory; any raw-ANSI or forcing finding is either explained or catalogued as a divergence.

W5. Tag + repin (post-merge, outside the PR)

After merge: cut the next manual tag (docs + repo mechanics only; no exported-symbol changes, so the working-with-state §6 release train does not require a consumer-matrix pass — additive/no-op). Patch-level bump from v0.3.0 → v0.3.1. Consumer repins are opportunistic (they pin standards via module version, so they read stale docs until repinned) — note this in the merge comment on #55; actual repin PRs in consumer repos are out of scope.

• Check: tag exists post-merge; chore: credstore dependency surface + cli-common self-conformance (standards-review level 2) #55 closes with the repin note.

TDD assessment

The only behavior-bearing changes are Makefile/CI mechanics (verified by running them) and docs. No Go source changes → no new tests. The W3 Makefile change is self-verifying (make check must run build).

Out of scope

• The upstream ByteNess PR and the consumer -tags rollout (chore: upstream opt-out build tag to ByteNess/keyring for the 1Password backends #57).
• Splitting cli-common's CI jobs; adding pr-title to this repo (rides the family composite rollout, ci.md §8).
• Consumer repin PRs.

[rianjs]

Item 1 quantification results (and one correction)

Correction to the issue body: ByteNess/keyring is pull-only for us (gh api repos/byteness/keyring → push: false) — "we control the fork" was wrong. Decision (2026-06-11): document-only here; the upstream opt-out-build-tag PR is committed separately in #57, which carries the full validated design (the five op*.go files are the only SDK importers, already constraint-gated !freebsd, init-registered — so the tag is a ~10-line-header PR with an existing pattern to follow).

Measurements (keyring v1.9.3, 2026-06-11):

• go list -deps ./credstore: 63 packages from the wazero / jaeger / 1Password / OTel trees (wazero 34, jaeger-client-go 19).
• Shipped slck binary: 5,393 surviving symbols from those trees — no dead-code elimination (the openers self-register via init()).
• go tool nm -size: ~10.6 MB attributable symbol bytes.
• govulncheck ./... on slack-chat-api: 0 reachable vulnerabilities; 13 vulnerability findings in required modules that the code never calls — the module-graph audit noise this finding predicted (per-module attribution not broken down; some findings may be in unrelated required modules).

Disposition of the item-1 checklist: quantify ✅ (above); fix path → re-routed to #57 (upstream PR + consumer -tags rollout when merged); interim documentation ✅ in the PR for this issue (working-with-secrets.md §1.10 "Known dependency cost" paragraph).

[rianjs]

Merged in #58; tagged v0.3.1 (docs + repo mechanics only, no exported API changes — no consumer release train required per working-with-state §6). Consumers pin standards via module version, so repins are opportunistic: gro / nrq / slck / atlassian (shared+cfl+jtk) are on v0.2.2, codereview on v0.3.0. Upstream keyring work continues in #57.