docs: resolve standards-family contradictions, gaps, and stale references by rianjs · Pull Request #56 · open-cli-collective/cli-common

rianjs · 2026-06-11T10:59:19Z

Resolves the standards-family contradictions, gaps, and stale references surfaced by the full two-level docs review. All maintainer decisions are recorded in #54; this PR is docs-only.

Changes

--force on nuclear data verbs — working-with-state.md §5.5 now uses the family-wide safety-skip spelling from command-surface.md §3.1; --yes dropped (decision rows annotated with the amendment, not rewritten).
set-credential exit codes soften to SHOULD — binary 0/non-0 is the MUST; per-class codes become normative when the typed-error layer (scriptability.md §3.2) ships. The two docs now agree.
Color stance flips to isatty-gated — output-and-rendering.md §8 requires auto-disable on non-TTY output (the fatih/color and lipgloss default); --no-color MUST, NO_COLOR SHOULD. Per-CLI verification tracked in chore: credstore dependency surface + cli-common self-conformance (standards-review level 2) #55.
AI-mention blocklist enforced in CI — ci.md §2's pr-title check also greps PR title + body; repo-layout.md §7 documents the squash-merge blind spot and which enforcement point covers which squash-message mode.
Library-repo profile — new repo-layout.md §2.1: required-files delta, check = tidy+lint+test+build, manual tagging (auto-release N/A), identity-check N/A. Scoped so chore: credstore dependency surface + cli-common self-conformance (standards-review level 2) #55's mechanical work satisfies it.
Run-number sharp edge — release.md §2/§6: GITHUB_RUN_NUMBER is workflow-file-path-scoped; renaming auto-release.yml regresses tags; recovery is a MAJOR.MINOR bump.
Newline-in-cell rule — output-and-rendering.md §4.1: embedded newlines/CRs replaced with a single space, same posture as the | collision rule.
Snapshot zeroing softened — working-with-secrets.md §1.5.1/§2.1 now promise best-effort clearing (Go cannot guarantee string zeroization), matching what credstore/bundle.go delivers.
Doc-rot — README §5a/§5b → §6a/§6b; working-with-state.md §7 step 7 records statedir.Data (DataDir()/DataDirEnsured()) as delivered in a9a6987; superseded disposition rows annotated.
Primer removed — docs/data-pillar-primer.md deleted; the decisions log in working-with-state.md §8 is the surviving record.

Verification

Contradiction sweep (greps for --yes, isatty, distinct code, zero, primer references, §5a/§5b) — every remaining hit is either the rule itself or a dated historical annotation.
make check green.

Closes #54

…nces Decisions applied (2026-06-11): - working-with-state $5.5: --force (long-only) replaces --yes on nuclear data verbs, aligning with command-surface $3.1's single safety-skip spelling; $8 decision rows annotated, not rewritten - working-with-secrets $1.5.2: set-credential per-class exit codes soften to SHOULD (binary 0/non-0 is the MUST) pending the typed-error layer; scriptability $3.1 lead aligned - output-and-rendering $8/$10: color stance flips to isatty-gated (the recommended libraries' default); per-CLI verification tracked in #55 - ci.md $2 + repo-layout $7: pr-title check also greps PR title and body against the AI-tooling blocklist (squash-merge blind spot); sample workflow comment ref fixed to release.md $1.1 - repo-layout $2.1: new library-repo profile (required-files delta, check=tidy+lint+test+build, manual tagging, identity-check N/A); $4 exemption tightened to include build in check - release.md $2/$6: GITHUB_RUN_NUMBER path-scope sharp edge (rename resets numbering and regresses tags; bump MAJOR.MINOR to recover) - output-and-rendering $4.1: newline-in-cell substitution rule - working-with-secrets $1.5.1/$2.1: snapshot zeroing softened to best-effort (Go cannot guarantee string zeroization) - doc-rot: README $5a/$5b -> $6a/$6b; working-with-state $7 step 7 records statedir.Data DataDir()/DataDirEnsured() as delivered (a9a6987); stale disposition rows annotated - remove docs/data-pillar-primer.md (superseded by working-with-state $5; decisions log is the surviving record) Closes #54

rianjs · 2026-06-11T11:00:31Z

Findings

Major: docs/scriptability.md:70 still says working-with-secrets.md defines an “exit-code-per-failure-class contract.” That preserves the old strict requirement this PR is supposed to soften. It now conflicts with docs/scriptability.md:79 and docs/working-with-secrets.md:211, where binary success/failure is the MUST and per-class codes are only SHOULD until the typed-error layer ships. Reword this cross-ref to something like “binary success/failure contract plus advisory per-class mapping.”
Minor: docs/repo-layout.md:214 says the landing commit is built from the “PR title and body,” while docs/ci.md:69-75 correctly gives the mode-specific split: title-only, title-and-description, or commit-details. This should use the same conditional wording as ci.md so the two docs do not reintroduce a squash-message contradiction.

…wording

rianjs · 2026-06-11T11:02:00Z

Findings

No findings.

The fixes address the remaining architectural issues: scriptability.md now preserves the binary-MUST/per-class-advisory split, and repo-layout.md now matches ci.md’s mode-conditional squash wording. The remaining grep hits for --yes, deleted primer references, and old §5a mentions are historical annotations rather than live policy.

The PR stays docs-only, matches the #54 maintainer decisions, and keeps #55’s mechanical/code work out of scope.

rianjs · 2026-06-11T11:02:23Z

This PR is documentation-only — nine files updated (standards clarifications, a stale primer deleted, doc-rot fixed) with no changes to Go source, tests, or configuration. No test coverage is required or applicable.

monit-reviewer

Automated PR Review

Reviewed commit: 37d189e

Approved with 1 non-blocking suggestion below. Address at your discretion.

Summary

Reviewer	Findings
documentation:docs-reviewer	1

documentation:docs-reviewer (1 findings)

💡 Suggestion - docs/ci.md:221

Cross-reference inconsistency: the job table (~line 56) cites release.md §1 for the conventional-commit check, but the YAML comment at this line cites release.md §1.1. One of the two should be made consistent — either both say §1 (the top-level section) or both say §1.1 (the grammar subsection).

1 info-level observations excluded. Run with --verbose to include.

3 PR discussion threads considered.

Completed in 2m 29s | $1.42 | sonnet | daemon 0.2.127 | Glorfindel

Field	Value
Model	sonnet
Reviewers	hybrid-synthesis, documentation:docs-reviewer, harness-engineering:harness-architecture-reviewer, harness-engineering:harness-enforcement-reviewer, harness-engineering:harness-knowledge-reviewer
Engine	claude · sonnet
Reviewed by	pr-review-daemon · monit-pr-reviewer
Duration	2m 29s wall · 2m 27s compute (Reviewers: 2m 01s · Synthesis: 25s)
Cost	$1.42 (estimated)
Tokens	270.6k in / 12.9k out
Turns	10

Per-workstream usage

Workstream	Model	In	Out	Cache read	Cache create	Cost
hybrid-synthesis	sonnet	36.5k	1.1k	13.8k	22.7k (1h)	$0.16
documentation:docs-reviewer	sonnet	60.9k	6.2k	13.8k	47.2k (1h)	$0.38
harness-engineering:harness-architecture-reviewer	sonnet	56.2k	530	13.8k	42.4k (1h)	$0.27
harness-engineering:harness-enforcement-reviewer	sonnet	59.0k	3.0k	13.8k	45.3k (1h)	$0.32
harness-engineering:harness-knowledge-reviewer	sonnet	57.9k	2.0k	13.8k	44.1k (1h)	$0.30

_{Re-reviews only run when @monit-reviewer is re-requested as a reviewer — push as many commits as you need, then re-request when ready. PRs targeting branches other than main, master are skipped, even when @monit-reviewer is re-requested.}

monit-reviewer · 2026-06-11T11:05:09Z

@@ -212,7 +220,7 @@ jobs:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest


🔵 Low (documentation:docs-reviewer): Cross-reference inconsistency: the job table (~line 56) cites release.md §1 for the conventional-commit check, but the YAML comment at this line cites release.md §1.1. One of the two should be made consistent — either both say §1 (the top-level section) or both say §1.1 (the grammar subsection).

Reply to this thread when addressed.

rianjs · 2026-06-11T11:06:10Z

Findings

No findings.

The daemon-driven cross-ref change in ci.md is consistent with the YAML comment and the actual grammar owner in release.md §1.1. I do not see architectural drift: the PR remains docs-only, keeps #55 work out of scope, and the policy changes still align with the maintainer decisions for #54.

docs: align stale cross-refs with softened exit-code and squash-mode …

37d189e

…wording

monit-reviewer approved these changes Jun 11, 2026

View reviewed changes

docs: cite release.md $1.1 consistently for the pr-title grammar

edae33c

rianjs merged commit 17c9dbf into main Jun 11, 2026
4 checks passed

rianjs deleted the docs/54-standards-review-fixes branch June 11, 2026 11:07

rianjs mentioned this pull request Jun 11, 2026

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

Closed

10 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: resolve standards-family contradictions, gaps, and stale references#56

docs: resolve standards-family contradictions, gaps, and stale references#56
rianjs merged 3 commits into
mainfrom
docs/54-standards-review-fixes

rianjs commented Jun 11, 2026

Uh oh!

rianjs commented Jun 11, 2026

Uh oh!

rianjs commented Jun 11, 2026

Uh oh!

rianjs commented Jun 11, 2026

Uh oh!

monit-reviewer left a comment

Uh oh!

monit-reviewer Jun 11, 2026

Uh oh!

rianjs commented Jun 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -212,7 +220,7 @@ jobs:
		if: github.event_name == 'pull_request'
		runs-on: ubuntu-latest

Uh oh!

Conversation

rianjs commented Jun 11, 2026

Changes

Verification

Uh oh!

rianjs commented Jun 11, 2026

Findings

Uh oh!

rianjs commented Jun 11, 2026

Findings

Uh oh!

rianjs commented Jun 11, 2026

Uh oh!

monit-reviewer left a comment

Choose a reason for hiding this comment

Automated PR Review

Summary

Uh oh!

monit-reviewer Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

rianjs commented Jun 11, 2026

Findings

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants