fix(verify-unixy-cli): defer ARG5 to verify-readme and correct the package rules #42
Loading…
Reference in a new issue
No description provided.
Delete branch "align/verify-unixy-cli"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
ARG5 carried a second README contract that diverged from verify-readme (three required sections vs nine, "under 10 lines" vs one paragraph) — it now defers to verify-readme by name. PKG3 read as an exact
^14requirement, failing any repo on commander 15, and now states a floor; PKG4 claimedinquireris deprecated, which the registry does not support — the prefer-@inquirer/promptsguidance stays; INT2 gains INT1's alternatives carve-out so a CLI legitimately following INT3 passes. Philosophy stubs, ARG9, and heading structure untouched, as ruled.Approach review: The approach is sound.
verify-readmeremoves the duplicate rather than trying to keep the two in sync. I checkedskills/verify-readme/SKILL.md: it covers everything ARG5 dropped — CLI pipeline patterns in the Usage section, and an Agent Rule template that requiresnpx -y <tool> --helpfirst plus a why-not-how paragraph. Nothing was lost in the move. Cross-skill reference by name also matches existing practice (verify-readmeinvokeshuman-facing-writing-stylethe same way).commanderlatest is 15.0.0 and@commander-js/extra-typingslatest is 15.0.0, so the old^14.0.0phrasing would have failed a current, correct project; the floor wording fixes that without inventing a ceiling.inquirerlatest (14.0.2) carries no deprecation marker on the registry, so dropping the deprecation claim while keeping the modularity/tree-shaking/TypeScript rationale for@inquirer/promptskeeps the rule true and still actionable.--dry-runclause is the meaningful delta and it is stated explicitly.No dangling references remain: the only other README mention (ARG8's Requirements section) is independent of ARG5 and is also covered by
verify-readme's Requirements slot. One small durability note on the ARG5 file below.Approach review by Claude Code Opus (opus)
@ -34,3 +5,1 @@- Verify the rule tells agent to run `--help` first- Verify the rule explains WHY (not HOW) to use the tool- Confirm the rule is concise (under 10 lines)**How to verify**: Apply the verify-readme skill to the CLI's README.Deferring to
verify-readmeis the right structure, but ARG5 now has zero self-contained content, and skills here are selected per run — a session that loadsverify-unixy-cliwithoutverify-readmegets a rule that says only "apply a skill you do not have," and the auditor either skips ARG5 or improvises a contract.Consider keeping a one-line fallback so the rule degrades instead of vanishing, e.g. "If
verify-readmeis unavailable, check at minimum for a Quick Start, CLI-composition examples in Usage, and an Agent Rule section." That preserves the single source of truth (no second contract to drift) while leaving the rule verifiable on its own.Deliberate decision — not changing. ARG5 stays a pure by-name deferral to
verify-readme, with no local fallback list. The suggested minimum-sections line would reintroduce a second, smaller README contract inside this file, which is exactly the drift-prone shape this PR removes: the previous local contract had already diverged fromverify-readme(three required sections vs nine). Whenverify-readmeis not part of the run, skipping ARG5 (a Warning-severity rule) is the intended degradation; a mini-contract that ages independently would fail worse than an honest skip.Summary: Reviewed the six changed skill/reference files. The substantive claims in the PR check out:
commanderand@commander-js/extra-typingsare both at 15.0.0 on the registry (so the old^14.0.0phrasing did fail current repos), the registry lists no deprecatedinquirerversions (latest 14.0.2), andverify-readmedoes cover everything ARG5 dropped (Quick Start §3, pipeline patterns §4, Agent Rule §8 + template). Three issues found: 1 medium, 2 low.How to verifyline still demands--force, contradicting the new INT3 carve-out note directly above it.npxrationale claims barenpxprompts in CI; npm suppresses the prompt under non-TTY/CI.verify-readme, which isn't guaranteed to be delivered in the same run.Code review by Claude Code Opus (opus)
@ -15,3 +15,3 @@**Pipeline examples**: CLIs that output data should include an example showing how to filter, sort, or aggregate output using standard Unix tools. This teaches composability and demonstrates the output format is pipe-friendly. Skip if the CLI doesn't produce pipe-friendly output.**npx example format**: If an example runs the CLI through `npx`, use `npx -y` explicitly (for example, `npx -y mycli --help`). Do not use bare `npx`. This avoids interactive install prompts and keeps examples deterministic in fresh environments and CI.**npx example format**: If an example runs the CLI through `npx`, use `npx -y` explicitly (for example, `npx -y mycli --help`) — bare `npx` stops on an interactive install prompt in fresh environments and CI.🟢 Low: The new rationale overstates what bare
npxdoes in CI. Inlibnpmexec(checked against npm 11.17.0,lib/index.js), the install confirmation is only read when stdin is a TTY and CI is not detected; undernoTTY() || ciInfo.isCIit logsThe following package was not found and will be installed: …and proceeds. So barenpxdoesn't stop on a prompt in CI — it stops only in an interactive shell without the package cached (and--no/npm_config_yes=falseturns it into a hard error). The previous wording ("avoids interactive install prompts and keeps examples deterministic") was accurate; consider e.g. "— barenpxstops on an interactive install prompt when the package isn't cached locally."Fixed in
17d3bb5with the suggested wording: the rationale now says barenpxstops on an interactive install prompt when the package isn't cached locally, dropping the CI claim — matching thelibnpmexecbehavior you cite (prompt only when TTY and not CI).@ -34,3 +5,1 @@- Verify the rule tells agent to run `--help` first- Verify the rule explains WHY (not HOW) to use the tool- Confirm the rule is concise (under 10 lines)**How to verify**: Apply the verify-readme skill to the CLI's README.🟢 Low: ARG5 now has no self-contained content, so it fails closed when
verify-readmeisn't part of the run.axskillsdelivers only the selected skills per launch, andverify-unixy-clican be selected withoutverify-readme; an agent that can't resolve the skill has nothing left to check here. (verify-readme->human-facing-writing-styledegrades gracefully — only prose polish is lost — whereas this leaves the whole rule empty.) A one-line fallback would close the gap, e.g. "If the verify-readme skill isn't available, check at minimum for a Quick Start, pipeline examples (ARG3 criteria), and an Agent Rule section that points atnpx -y <cli> --help."Deliberate decision — not changing. ARG5 stays a pure by-name deferral to
verify-readme, with no local fallback list. The suggested minimum-sections line would reintroduce a second, smaller README contract inside this file, which is exactly the drift-prone shape this PR removes: the previous local contract had already diverged fromverify-readme(three required sections vs nine). Whenverify-readmeis not part of the run, skipping ARG5 (a Warning-severity rule) is the intended degradation; a mini-contract that ages independently would fail worse than an honest skip.@ -2,6 +2,8 @@Default behavior should be non-destructive. Destructive operations must refuse without `--force`/`-f` and provide `--dry-run` to preview what would happen.> **Note:** INT3 provides a less strict alternative for destructive-operation confirmations. A CLI that follows INT3 instead of the strict `--force`-only approach here is compliant — see INT3 for requirements. The `--dry-run` requirement applies either way.🟡 Medium: The new carve-out isn't reflected in the rule's checklist. The last line of this file still reads "Verify destructive actions refuse by default without
--force", so a verifier that jumps to How to verify (which the SKILL.md workflow encourages) will still fail an INT3-style CLI — exactly the false failure this note is meant to prevent. Update the closing line to something like: "Check for--dry-runand--force. Verify destructive actions are non-destructive by default: either refusing without--force, or gating behind an INT3-compliant confirmation." (INT1'sHow to verifybullet — "Verify destructive operations refuse without--force, not prompt for confirmation" — has the same unpatched contradiction with its own note, though that file is outside this diff.)Fixed in
17d3bb5. The closing line now reads: "Verify destructive actions are non-destructive by default: either refusing without--force, or gating behind an INT3-compliant confirmation." Also applied the same correction to INT1's third How-to-verify bullet, which carried the identical contradiction with its own INT3 note — the two files' carve-outs are deliberately kept in lockstep.Summary: Found 2 medium and 1 low issue in a documentation-only change to the
verify-unixy-cliskill.I checked the registry claims the PR rests on:
commanderis at15.0.0and@commander-js/extra-typingsalso publishes15.0.0, so PKG3's new floor wording and its^15.0.0example are accurate;inquireris at14.0.2(published 2026-05-31) with no npmdeprecatedfield, so removing the "deprecated" claim from PKG4 is correct. The ARG5 deferral does not lose much substance —verify-readmecovers the Agent Rule template (withnpx -y) and CLI pipeline patterns.The remaining findings are residual inconsistencies in the two lines this PR rewrote: INT2's verify step still demands
--forceunconditionally despite the new INT3 carve-out, and PKG3's verify step still requires@commander-js/extra-typingsfor JavaScript-only CLIs.Code review by Claude Code Opus (opus)
@ -1,36 +1,5 @@# ARG5. README Quality (Warning)The README must include these sections:The verify-readme skill is the canonical README contract — required sections, their order, and the agent-rule requirements all live there. Audit the README against that skill.🟢 Low: The rule now has no self-contained content: if
verify-readmeisn't part of the run's skill selection, ARG5 becomes unverifiable with nothing to fall back on.axskillsdelivers a per-run selection, so co-delivery isn't guaranteed. Consider pointing at the file (skills/verify-readme/SKILL.mdin this source) and adding a one-line fallback for when the skill isn't loaded — e.g. check for Quick Start, CLI pipeline examples in Usage, and an Agent Rule section. Cross-skill references are established here (verify-readmeinvokeshuman-facing-writing-style), so this is about the missing fallback, not the deferral itself.Deliberate decision — not changing. ARG5 stays a pure by-name deferral to
verify-readmewith no local fallback: a minimum-sections fallback line is a second, smaller README contract in this file, which is the drift-prone shape this PR removes (the previous local contract had already diverged to three sections vs verify-readme's nine). Whenverify-readmeis not in the run's selection, skipping ARG5 — a Warning-severity rule — is the intended degradation. The by-name (rather than source-path) reference is also deliberate: it matches existing cross-skill practice, and delivered skill layouts need not mirror this source tree.@ -17,3 +19,3 @@```**How to verify**: Check for `--dry-run` and `--force` options. Verify destructive actions refuse by default without `--force`.**How to verify**: Check for `--dry-run` and `--force` options. Verify destructive actions are non-destructive by default: either refusing without `--force`, or gating behind an INT3-compliant confirmation.🟡 Medium: The first sentence still undoes the carve-out the second sentence adds. INT3's escape hatches are
--yes/-y,--no-interactive, andCI=1— an INT3-compliant CLI has no--forceat all, so "Check for--dry-runand--forceoptions" makes it fail this rule, which is Critical. That is exactly the false positive the new note above is meant to remove.Suggested fix:
**How to verify**: Check for a--dry-runoption. Verify destructive actions are non-destructive by default: either refusing without--force, or gating behind an INT3-compliant confirmation.Fixed in
2c0aaa3with the suggested wording: the checklist now asks only for a--dry-runoption, and--forceappears only inside the either/or compliance test, so an INT3-compliant CLI without--forcepasses.@ -86,3 +86,3 @@## How to verify- `package.json` has `commander` and `@commander-js/extra-typings` at `^14.0.0`+- `package.json` declares `commander` and `@commander-js/extra-typings` at version 14 or newer (a range on a later major, e.g. `^15.0.0`, passes)🟡 Medium: This bullet requires every project to declare
@commander-js/extra-typings, but the next bullet scopes that package to TypeScript projects only ("Imports use@commander-js/extra-typings(notcommander) in TypeScript projects"). A JavaScript-only CLI that correctly depends oncommanderalone gets flagged as violating a Critical rule. The both-required phrasing predates this PR, but the line is being rewritten here.Suggested fix:
-package.jsondeclarescommanderat version 14 or newer — plus@commander-js/extra-typingsat a matching major for TypeScript projects (a range on a later major, e.g.^15.0.0, passes)Fixed in
2c0aaa3with the suggested wording:commanderat 14 or newer stays the universal floor, and@commander-js/extra-typingsis now scoped to TypeScript projects at a matching major, so a JavaScript-only CLI oncommanderalone passes.Summary: Docs-only change to the
verify-unixy-cliskill. The premises check out: the npm registry reportscommander@15.0.0as latest (so the old^14.0.0check would have failed any repo on 15) andinquirer@14.0.2with nodeprecatedfield, so dropping the deprecation claim is correct. The ARG5 deferral is well covered —skills/verify-readme/SKILL.mdincludes both the Agent Rule template and the CLI pipeline patterns that ARG5 used to own.Found 5 low-severity issues, all wording/consistency gaps in rules that an agent applies mechanically: an ambiguous
@commander-js/extra-typingsversion check, an npx claim that is unconditional but only holds on an interactive TTY, ARG5 having no fallback ifverify-readmeis not delivered in the same run, and two leftover contradictions with the INT3 carve-out. No blocking defects.Code review by Claude Code Opus (opus)
@ -15,3 +15,3 @@**Pipeline examples**: CLIs that output data should include an example showing how to filter, sort, or aggregate output using standard Unix tools. This teaches composability and demonstrates the output format is pipe-friendly. Skip if the CLI doesn't produce pipe-friendly output.**npx example format**: If an example runs the CLI through `npx`, use `npx -y` explicitly (for example, `npx -y mycli --help`). Do not use bare `npx`. This avoids interactive install prompts and keeps examples deterministic in fresh environments and CI.**npx example format**: If an example runs the CLI through `npx`, use `npx -y` explicitly (for example, `npx -y mycli --help`) — bare `npx` stops on an interactive install prompt when the package isn't cached locally.🟢 Low: The new rationale is stated unconditionally but only holds on an interactive terminal. In npm 11 (
libnpmexec/lib/index.js), the missing-package branch isif (noTTY() || ciInfo.isCI) { log.warn(...) } else { prompt }— so in CI or any non-TTY invocation barenpxwarns and installs anyway rather than stopping, and it only hard-fails when--nois passed. The old wording covered this by also citing determinism; the replacement drops it. Suggest scoping the claim, e.g.bare npx stops on an interactive install prompt when the package is not cached locally and stdin is a TTY.Fixed in
7a4214a: the claim is now scoped to "when the package isn't cached locally and stdin is a TTY", and the determinism rationale the old wording carried is restored alongside it.@ -1,36 +1,5 @@# ARG5. README Quality (Warning)The README must include these sections:The verify-readme skill is the canonical README contract — required sections, their order, and the agent-rule requirements all live there. Audit the README against that skill.🟢 Low: ARG5 now carries zero self-contained criteria, so it is unverifiable whenever
verify-readmeis not part of the same run. Per the repo README,axskillsdelivers only the skills selected for that agent launch, andverify-unixy-clican be selected withoutverify-readme— the audit would then silently skip a Warning-level rule with no signal to the user. (The same by-name cross-skill reference already exists inverify-readmepointing athuman-facing-writing-style, so this is a pattern, not a regression.) Two cheap mitigations: name the file path (skills/verify-readme/SKILL.md) so it can be read directly when the skill is not loaded, and add a one-line fallback naming the CLI-specific minimum (anAgent Rulesection plus pipeline examples inUsage) for when it is unavailable.Deliberate decision — not changing (same ruling as the parallel threads on this file). ARG5 stays a pure by-name deferral to
verify-readmewith no local fallback list: a minimum-sections fallback is a second, smaller README contract, the drift-prone shape this PR removes. Skipping ARG5 (Warning severity) whenverify-readmeisn't in the run is the intended degradation, and the by-name rather than source-path reference is deliberate — delivered skill layouts need not mirror this source tree.@ -45,3 +45,3 @@- Run the CLI without required arguments — confirm it exits non-zero with an actionable error, not a prompt- Search for prompt/readline usage and verify all prompts are gated by `--interactive` flag- Verify destructive operations refuse without `--force`, not prompt for confirmation- Verify destructive operations are non-destructive by default: either refusing without `--force`, or gating behind an INT3-compliant confirmation🟢 Low: The checklist line now accepts an INT3-compliant confirmation, but the example block above still contradicts it: line 38 labels
# Bad: prompts for confirmation based on TTYwith? Delete 2 files? (y/N), and the opening paragraph still saysrefuse without --force, don't prompt for confirmation. An agent reading top-to-bottom will flag an INT3-compliant CLI as an INT1 violation on the strength of that example. Worth annotating the Bad example (e.g.Bad: prompts based on TTY with no --yes/--no-interactive/CI escape hatches — see INT3) so the example and the checklist agree.Fixed in
7a4214a: the Bad example is now labeled "prompts for confirmation based on TTY alone — no --yes/--no-interactive/CI escape hatches (see INT3)", so the example and the checklist agree that a hatch-less TTY prompt is what fails.@ -2,6 +2,8 @@Default behavior should be non-destructive. Destructive operations must refuse without `--force`/`-f` and provide `--dry-run` to preview what would happen.> **Note:** INT3 provides a less strict alternative for destructive-operation confirmations. A CLI that follows INT3 instead of the strict `--force`-only approach here is compliant — see INT3 for requirements. The `--dry-run` requirement applies either way.🟢 Low: The carve-out is one-directional.
int3-tty-based-confirmations.mdstill opens withThis rule is an alternative to INT1's strict --force-only approachandA CLI may follow either INT1 or INT3 — not both; it never mentions INT2, nor that INT2's--dry-runrequirement still applies when a CLI takes the INT3 route. Since INT2 is Critical, an agent that reads INT3 first can conclude the INT3 path exempts it from INT2 entirely. Updating INT3 to name both INT1 and INT2 and to restate that--dry-runstill applies would close the round-trip.Fixed in
7a4214a: INT3's opening paragraph now closes the round-trip with "Following INT3 replaces only the confirmation approach — INT2's--dry-runrequirement applies either way", echoing INT2's boundary sentence verbatim so the two files cannot drift apart in meaning.@ -86,3 +86,3 @@## How to verify- `package.json` has `commander` and `@commander-js/extra-typings` at `^14.0.0`+- `package.json` declares `commander` at version 14 or newer — plus `@commander-js/extra-typings` at a matching major for TypeScript projects (a range on a later major, e.g. `^15.0.0`, passes)🟢 Low: The bullet is ambiguous about which major
@commander-js/extra-typingsmust be on. Read literally,commander at version 14 or newerplusa range on a later major, e.g. ^15.0.0, passespermitscommander: ^14.0.0with@commander-js/extra-typings: ^15.0.0, which fails peer resolution: the registry shows@commander-js/extra-typings@15.0.0declaringpeerDependencies: { commander: ~15.0.0 }and14.0.0declaring~14.0.0. The two majors must be equal, not merely both >= 14. Suggest tightening to something like:@commander-js/extra-typingsat the same major as the declaredcommander(its peer range pins that major), socommander: ^15.0.0+extra-typings: ^15.0.0passes.Fixed in
7a4214a: the bullet now reads "commanderat version 14 or newer (a range on a later major, e.g.^15.0.0, passes) — TypeScript projects also declare@commander-js/extra-typingsat the same major ascommander(its peer range pins that major)", so a cross-major pairing no longer reads as passing.Approach review: Sound direction. The four changes each remove a real defect in the rule set rather than papering over it:
verify-readmeis the right call.skills/verify-readme/SKILL.mdalready covers everything ARG5 was asserting for a CLI — Quick Start, a CLI Usage section with pipeline patterns, and an Agent Rule template that mandatesnpx -y <tool> --helpas the first instruction — so the deletion loses no coverage and kills a contract that could disagree with itself. Naming a sibling skill by name is established practice here (verify-readmeinvokeshuman-facing-writing-stylethe same way), so the cross-skill dependency is consistent with the repo, not a new pattern.--forceunconditionally, so an INT3-compliant CLI failed a Critical rule. Repeating the note in each rule file rather than centralizing it fits the one-file-per-rule design, where a reader may load only INT2.^14and PKG4 dropping the deprecation claim are both factually right: the registry currently publishescommander@15.0.0with no deprecation oninquirer@14.0.2, so the old text would have failed a current-on-commanderrepo and asserted something the registry does not say. Keeping the prefer-@inquirer/promptsguidance on modularity/typing grounds is the durable justification.One narrow suggestion on the
@commander-js/extra-typingscriterion — see the inline comment. No other material alternative; the SKILL.md workflow condensation is a restructure of the same steps and does not change what the audit does.Approach review by Claude Code Opus (opus)
@ -86,3 +86,3 @@## How to verify- `package.json` has `commander` and `@commander-js/extra-typings` at `^14.0.0`+- `package.json` declares `commander` at version 14 or newer (a range on a later major, e.g. `^15.0.0`, passes) — TypeScript projects also declare `@commander-js/extra-typings` at the same major as `commander` (its peer range pins that major)The same-major coupling restates the peer range slightly wrong, and restating it is what makes the criterion rot in the first place.
@commander-js/extra-typings@15.0.0declarespeerDependencies: { commander: '~15.0.0' }— a tilde range, so it pins the minor, not the major. A repo oncommander@15.1.xwithextra-typings@15.0.xmatches "the same major" but fails the actual peer range, so an audit following this bullet would pass a tree npm rejects.Since the point of this rewrite is to state a floor instead of a pin, apply the same move here and delegate to the range rather than describing it: require that the declared
@commander-js/extra-typingsversion satisfy its own peer range against the declaredcommander. That check stays correct whether upstream ships~,^, or an exact peer, and needs no edit at the next major.Fixed in
ae0ea2aby delegating to the peer range as suggested: the bullet now requires@commander-js/extra-typingsat a version whose peer range accepts the declaredcommander, noting upstream pins tighter than the major (~15.0.0) — so the criterion no longer restates a range that can rot.Summary: Found 4 medium issues.
Code review by Codex GPT-5.6 SOL (gpt-5.6-sol)
@ -1,36 +1,5 @@# ARG5. README Quality (Warning)The README must include these sections:The verify-readme skill is the canonical README contract — required sections, their order, and the agent-rule requirements all live there. Audit the README against that skill.🟡 Medium:
verify-readmeis a separately selectable skill, but this repository has no dependency manifest that causes it to be delivered withverify-unixy-cli. When a user selects only this skill, ARG5 now has no contract available to read and the audit cannot execute this rule. Bundle the canonical reference/dependency with this skill, or add a delivery-level dependency or fallback before removing the local requirements.Deliberate decision — not changing (same ruling as the earlier threads on this file). ARG5 stays a pure by-name deferral to
verify-readmewith no bundled copy or fallback list: a local minimum would be a second README contract, the drift-prone shape this PR removes — the old local contract had already diverged to three sections vs verify-readme's nine. Whenverify-readmeisn't in the run's selection, skipping ARG5 (Warning severity) is the intended degradation. Cross-skill by-name references are established practice here, as the approach review on this head also notes.@ -45,3 +45,3 @@- Run the CLI without required arguments — confirm it exits non-zero with an actionable error, not a prompt- Search for prompt/readline usage and verify all prompts are gated by `--interactive` flag- Verify destructive operations refuse without `--force`, not prompt for confirmation- Verify destructive operations are non-destructive by default: either refusing without `--force`, or gating behind an INT3-compliant confirmation🟡 Medium: The INT3 exception added here conflicts with the verification bullet immediately above, which still requires every prompt to be gated by
--interactive. An INT3 confirmation intentionally prompts based on TTY without that flag, so a compliant CLI will still be failed under INT1. Exempt destructive INT3 confirmations from the earlier prompt-gating check.Fixed in
ae0ea2a: the prompt-gating bullet now exempts destructive-operation confirmations on the INT3 path, which are gated by INT3's TTY check and escape hatches rather than--interactive, so an INT3-compliant CLI no longer fails that bullet.@ -2,6 +2,8 @@Default behavior should be non-destructive. Destructive operations must refuse without `--force`/`-f` and provide `--dry-run` to preview what would happen.> **Note:** INT3 provides a less strict alternative for destructive-operation confirmations. A CLI that follows INT3 instead of the strict `--force`-only approach here is compliant — see INT3 for requirements. The `--dry-run` requirement applies either way.🟡 Medium: This carve-out contradicts the rule sentence above, which still unconditionally says destructive operations must refuse without
--force. Depending on which normative sentence the auditor follows, an INT3-compliant CLI both passes and fails. Rewrite the opening contract to permit either force-based refusal or an INT3 confirmation while retaining the--dry-runrequirement.Deliberate decision — not changing. The carve-out's shape (strict normative sentence, immediately qualified by the INT3 note) is copied verbatim from INT1 by design, and that parity is a user ruling on this PR: each reference file is read standalone, so both files state the strict default and then name the accepted alternative in the very next paragraph. The note explicitly says an INT3-following CLI "is compliant", and the How-to-verify line now encodes the either/or, so neither entry point yields a false failure. Integrating the alternative into the contract sentence here would break the INT1/INT2 parallel or force the same rewrite onto INT1, which is outside this PR's scope.
@ -86,3 +86,3 @@## How to verify- `package.json` has `commander` and `@commander-js/extra-typings` at `^14.0.0`+- `package.json` declares `commander` at version 14 or newer (a range on a later major, e.g. `^15.0.0`, passes) — TypeScript projects also declare `@commander-js/extra-typings` at the same major as `commander` (its peer range pins that major)🟡 Medium: Matching only the major is insufficient: the published
@commander-js/extra-typings@14.0.0peer dependency iscommander: ~14.0.0, and its README says major and minor versions should match. This check would approve ranges that can install mismatched typings and Commander minors, then fail peer-dependency resolution. Require matching major and minor versions or otherwise verify compatible peer ranges.Fixed in
ae0ea2a: the bullet now delegates to peer resolution —@commander-js/extra-typingsmust be at a version whose peer range accepts the declaredcommander— rather than comparing majors, which as you note would pass a15.1.x/15.0.xtree npm rejects. This also stays correct if upstream ever loosens or tightens the peer range.Summary: No actionable defects found; 1 informational note.
I verified the factual claims this documentation-only PR rests on, rather than taking them at face value:
commanderlatest is15.0.0;@commander-js/extra-typings@15.0.0peerscommander: "~15.0.0"and@commander-js/extra-typings@14peerscommander: "~14.0.0". The new wording (floor of 14, later majors pass, peer range pinned tighter than the major so check peer resolution rather than matching majors) is accurate, and the tilde ranges do accept the14.0.xpatch line as implied.inquirer@14.0.2, last modified 2026-05-31, with nodeprecatedfield. Dropping the "deprecated / maintenance mode" claim and keeping the modular/tree-shakeable/TypeScript rationale for@inquirer/promptsis the correct fix.npx— checked npm's ownlibnpmexec: the install confirmation is skipped whennoTTY() || ciInfo.isCI, andnoTTYis exactly!process.stdin.isTTY. The revised sentence (prompt only when the package isn't cached locally and stdin is a TTY) matches the implementation precisely, unlike the previous unconditional claim.skills/verify-readme/SKILL.mddoes own the section order, the pipeline-patterns guidance, and the Agent Rule template, so the removed ARG5 contract is genuinely covered there; the two contradictory contracts (three sections vs nine, "under 10 lines" vs one paragraph) are gone.The INT1/INT2/INT3 carve-out is now reciprocal and closed: all three files agree that INT3 replaces only the confirmation approach, INT2's
--dry-runapplies on either path, and INT2/INT1 accept a confirmation only if it is "INT3-compliant" (i.e. with--yes,--no-interactive, andCIescape hatches), so a partially-implemented TTY confirmation still fails the Critical rules. INT1's mental-model line "Never prompt based on TTY alone" remains consistent, since INT3 requires TTY plus the escape-hatch flags. The SKILL.md workflow renumbering leaves no dangling step references, and all 37 rule-table links resolve to existing files.Code review by Claude Code Opus (opus)
@ -1,36 +1,5 @@# ARG5. README Quality (Warning)The README must include these sections:The verify-readme skill is the canonical README contract — required sections, their order, and the agent-rule requirements all live there. Audit the README against that skill.ℹ️ Info: ARG5 is now entirely delegated, so the rule is unverifiable in any run where
verify-unixy-cliis selected butverify-readmeis not —axskillsdelivers only the selected skills per launch (full-tree copies happen onaxskills syncfor Claude, not on every selection). Cross-skill delegation is an established convention in this repo (verify-readme→human-facing-writing-style,add-dark-mode→dark-mode-image→imagegen), so this matches house style and needs no change; noting it only because ARG5 retains no self-contained fallback the way those callers do, where the delegated skill covers one facet rather than the whole rule.Acknowledged. The whole-rule delegation with no local fallback is a deliberate ruling on this PR (see the resolved threads on this file): a fallback list would be a second README contract, the drift-prone shape this PR removes, and skipping ARG5 (Warning severity) when
verify-readmeisn't selected is the intended degradation.ae0ea2afc17c89ed2770History note: two review-fix commits were reworded (content untouched) because their subjects exceeded commitlint's 100-character header limit —
7a4214ais nowa460e5aandae0ea2ais now7c89ed2. In-thread "Fixed in" references map accordingly.Summary: Docs-only change to the
verify-unixy-cliskill. The three factual corrections check out against the npm registry:commanderlatest is 15.0.0,@commander-js/extra-typings15.0.0 declares peercommander: ~15.0.0(so PKG3's "check peer resolution, not matching majors" is right), andinquirer14.0.2 carries no deprecation on the registry, so dropping the "deprecated" claim is correct. The ARG3 npx claim is also accurate — barenpxonly prompts when the package is uncached and stdin is a TTY; non-TTY/CI runs install without prompting. The INT1/INT2/INT3 carve-outs are now mutually consistent, andverify-readmedoes cover everything ARG5 gave up (pipeline patterns in the CLI Usage section, the CLI-only Agent Rule template withnpx -y).Found 2 low-severity consistency issues; no correctness, security, or integration defects.
Code review by Claude Code Opus (opus)
@ -1,36 +1,5 @@# ARG5. README Quality (Warning)The README must include these sections:The verify-readme skill is the canonical README contract — required sections, their order, and the agent-rule requirements all live there. Audit the README against that skill.🟢 Low: Deferring the contract to
verify-readmeremoves the divergence, but it also leaves ARG5 unverifiable when that skill isn't present:axskillsdelivers only the selected skills per run, so a selection ofverify-unixy-clialone gives the auditing agent no README criteria at all, and the rule silently drops out of the report rather than being flagged. Worth naming the fallback in one line — e.g. "if theverify-readmeskill isn't available, record ARG5 as Unable to verify" (matching the SKILL.md workflow's existing "Unable to verify" state), or pointing at the sections it owns (Quick Start, CLI Usage pipeline examples, the CLI-only Agent Rule). Also consider backticking the skill name for consistency with how other files here reference sibling skills.Deliberate decision — not changing (same ruling as the resolved threads on this file across earlier heads). ARG5 stays a pure by-name deferral with no local criteria list; the sections-it-owns variant is the second-contract shape the ruling forbids. The "Unable to verify" recording needs no per-rule line either: that state is already the SKILL.md workflow's semantics for any rule the auditor cannot execute, ARG5 included. On backticking: the file consistently names verify-readme as prose ("The verify-readme skill …", "Apply the verify-readme skill"), so it is internally consistent; a fleet-wide spelling harmonization for sibling-skill references is out of this PR's scope.
@ -2,6 +2,8 @@Default behavior should be non-destructive. Destructive operations must refuse without `--force`/`-f` and provide `--dry-run` to preview what would happen.> **Note:** INT3 provides a less strict alternative for destructive-operation confirmations. A CLI that follows INT3 instead of the strict `--force`-only approach here is compliant — see INT3 for requirements. The `--dry-run` requirement applies either way.🟢 Low: The note resolves the carve-out, but the rule's normative sentence two lines above still reads "Destructive operations must refuse without
--force/-f", which now contradicts both this note and the revised How to verify below it. INT1 has the same note but its body sentence is at least followed immediately by the qualifier; here an agent skimming for the MUST can stop at line 3 and fail an INT3-compliant CLI on a Critical rule. Softening line 3 to something like "Destructive operations must be non-destructive by default — refuse without--force/-for confirm per INT3 — and provide--dry-runto preview" would make the rule statement and the verification step agree without needing the reader to reconcile them.Deliberate decision — not changing (same ruling as the resolved thread at this line from the previous head). The strict-sentence-plus-note shape is copied verbatim from INT1 by design, and that INT1-parity is a user ruling on this PR. The note sits two lines below the sentence in a 21-line file and states outright that an INT3-following CLI is compliant, and the How-to-verify line encodes the either/or — a reader cannot apply the MUST without passing the qualifier. Folding the alternative into the contract sentence here would break the INT1/INT2 parallel or force the same rewrite onto INT1, which is out of scope by ruling.