fix(skills): exit code verification should check the README pointer #111

Closed
jercik wants to merge 1 commit from fix/io3-verify-readme-pointer into fix/skills-point-to-sources
Owner

Addresses the IO3 verification clarification in #97 by checking its existing README pointer and retry-guidance requirement. This stacks on #97 and must merge after it.

Addresses the IO3 verification clarification in [#97](https://code.j4k.dev/j4k-oss/agent-skills/pulls/97#issuecomment-111907) by checking its existing README pointer and retry-guidance requirement. This stacks on #97 and must merge after it.
fix(skills): exit code verification should check the README pointer
All checks were successful
commit-msg / commitlint (pull_request) Successful in 22s
Review / Review (pull_request_target) Successful in 2m34s
Node tests / node:test (pull_request) Successful in 3m4s
4f6c27dd22

Review 01M422NY2KB9QFRBFA42W5JF6Q — head 4f6c27dd22f7fdc91eda7022449f0ed5750feb44

Review — j4k-oss/agent-skills @ b178c9c55e

Scope: diff against base tree df400b9b0b87
Status: dispatched — coverage complete (4/4 slots terminal)
Facts: current review-wide projection

Computed under:

{
  "abandonment": "abandonment-v1",
  "anchor_recipe": 1,
  "batch_policy": "batch-v1",
  "coverage": "coverage-v3",
  "dispatch_policy": "dispatch-v2",
  "grounder_version": 1,
  "grounding_read_rule": "grounding-read-v1",
  "promotion_policy": "promotion-v1",
  "report": "report-v3",
  "tally": "tally-v1",
  "triage_settle": "triage-settle-v2"
}

Findings (1)

low — The README check repeats the exit-code rule without adding a verification method

  • claim: 01M422RJ2QRMG5SBN9XXZXW97P
  • anchor: skills/verify-unixy-cli/references/io3-exit-codes.md (snippet)
Check that the README points at `--help` for the codes and keeps any retry guidance that help cannot show.
  • lens: writing-quality · arm: default
  • verdicts: 1 valid / 0 invalid / 0 uncertain
  • disposition: none

I read the full IO3 reference and the verify-unixy-cli audit workflow. The Multi-state verdicts paragraph immediately above this sentence already directs the reader to point the README at --help for codes and retain guidance help cannot show, including safe retry behavior. The audit workflow also says to verify each applicable rule. This added sentence restates that same instruction and supplies no distinct lookup or test, so readers encounter a second maintenance point for the same requirement. The writing-for-agents skill no-op test and One Idea, One Place guidance support deleting this final sentence while keeping the preceding rule and the other concrete exit-code checks in How to verify. The decisive refutation would be a separate verification operation supplied by this sentence; I found none in the surrounding text.

Other claims

  • grounding-pending (0)
  • ungrounded (0)
  • rejected (0)
  • duplicate-of (0)
  • unadjudicated (0)

Coverage

Coverage pass: 01M422NY4B2PSC3TF7W5ZR4CB8
Accounting: complete
Slot health: healthy

lens part arm unit status runs loss
general-bug whole default no-claims 1 no
writing-quality whole default claims-emitted 1 no
test-trimming whole default no-claims 1 no
restated-sets whole default no-claims 1 no
<!-- review:summary --> **Review** `01M422NY2KB9QFRBFA42W5JF6Q` — head `4f6c27dd22f7fdc91eda7022449f0ed5750feb44` # Review — j4k-oss/agent-skills @ b178c9c55ea2 Scope: diff against base tree `df400b9b0b87` Status: dispatched — coverage complete (4/4 slots terminal) Facts: current review-wide projection Computed under: ```json { "abandonment": "abandonment-v1", "anchor_recipe": 1, "batch_policy": "batch-v1", "coverage": "coverage-v3", "dispatch_policy": "dispatch-v2", "grounder_version": 1, "grounding_read_rule": "grounding-read-v1", "promotion_policy": "promotion-v1", "report": "report-v3", "tally": "tally-v1", "triage_settle": "triage-settle-v2" } ``` ## Findings (1) ### low — The README check repeats the exit-code rule without adding a verification method - claim: `01M422RJ2QRMG5SBN9XXZXW97P` - anchor: `skills/verify-unixy-cli/references/io3-exit-codes.md` (snippet) ``` Check that the README points at `--help` for the codes and keeps any retry guidance that help cannot show. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > I read the full IO3 reference and the verify-unixy-cli audit workflow. The Multi-state verdicts paragraph immediately above this sentence already directs the reader to point the README at `--help` for codes and retain guidance help cannot show, including safe retry behavior. The audit workflow also says to verify each applicable rule. This added sentence restates that same instruction and supplies no distinct lookup or test, so readers encounter a second maintenance point for the same requirement. The writing-for-agents skill no-op test and One Idea, One Place guidance support deleting this final sentence while keeping the preceding rule and the other concrete exit-code checks in How to verify. The decisive refutation would be a separate verification operation supplied by this sentence; I found none in the surrounding text. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (0) ## Coverage Coverage pass: 01M422NY4B2PSC3TF7W5ZR4CB8 Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | whole | default | claims-emitted | 1 | no | | test-trimming | whole | default | no-claims | 1 | no | | restated-sets | whole | default | no-claims | 1 | no |
@ -14,3 +14,3 @@
**Multi-state verdicts**: When the tool's verdict has more than two states, give each state its own documented exit code instead of making callers parse output. `grep` is the classic form — `0` match, `1` no match, `2` error — and `gh pr checks` the modern one: `0` passing, `1` failing, a documented `8` while checks are pending, so a script can wait on pending without scraping prose. Keep `0` for the good state, give each remaining state — errors included — its own nonzero code, and document every code in `--help`. When one table in the code maps states to codes, render help's list from that table. The README points at `--help` for the codes and keeps what help can't show, such as which codes are safe to retry. Avoid codes with reserved meanings: `126`–`127` (not executable / not found) and `128+n` (killed by signal `n`).
**How to verify**: Search for `process.exit()` and `process.exitCode` usage. Ensure success returns 0 and errors return non-zero. Test: run CLI without required args and verify exit code is non-zero. If the tool's domain has a more-than-binary verdict, check that distinct states get distinct exit codes and that `--help` documents them, rendered from the code's state-to-code table when one exists.
**How to verify**: Search for `process.exit()` and `process.exitCode` usage. Ensure success returns 0 and errors return non-zero. Test: run CLI without required args and verify exit code is non-zero. If the tool's domain has a more-than-binary verdict, check that distinct states get distinct exit codes and that `--help` documents them, rendered from the code's state-to-code table when one exists. Check that the README points at `--help` for the codes and keeps any retry guidance that help cannot show.

low — The README check repeats the exit-code rule without adding a verification method

I read the full IO3 reference and the verify-unixy-cli audit workflow. The Multi-state verdicts paragraph immediately above this sentence already directs the reader to point the README at --help for codes and retain guidance help cannot show, including safe retry behavior. The audit workflow also says to verify each applicable rule. This added sentence restates that same instruction and supplies no distinct lookup or test, so readers encounter a second maintenance point for the same requirement. The writing-for-agents skill no-op test and One Idea, One Place guidance support deleting this final sentence while keeping the preceding rule and the other concrete exit-code checks in How to verify. The decisive refutation would be a separate verification operation supplied by this sentence; I found none in the surrounding text.

lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain
claim 01M422RJ2QRMG5SBN9XXZXW97P of review 01M422NY2KB9QFRBFA42W5JF6Q

<!-- review:claim:01M422RJ2QRMG5SBN9XXZXW97P --> **low** — The README check repeats the exit-code rule without adding a verification method > I read the full IO3 reference and the verify-unixy-cli audit workflow. The Multi-state verdicts paragraph immediately above this sentence already directs the reader to point the README at `--help` for codes and retain guidance help cannot show, including safe retry behavior. The audit workflow also says to verify each applicable rule. This added sentence restates that same instruction and supplies no distinct lookup or test, so readers encounter a second maintenance point for the same requirement. The writing-for-agents skill no-op test and One Idea, One Place guidance support deleting this final sentence while keeping the preceding rule and the other concrete exit-code checks in How to verify. The decisive refutation would be a separate verification operation supplied by this sentence; I found none in the surrounding text. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M422RJ2QRMG5SBN9XXZXW97P` of review `01M422NY2KB9QFRBFA42W5JF6Q`
jercik marked this conversation as resolved
Author
Owner

Replying to review comment #111932

Candidate withdrawn: verify-unixy-cli requires reading each reference in full (line 22) and verifying every applicable rule with evidence (lines 79–81). IO3 already includes the README pointer and retry-guidance requirement. This candidate repeats that rule without a distinct verification operation; the source finding's sole-checklist premise is unsupported. The PR will close without merging.

> Replying to review comment #111932 Candidate withdrawn: verify-unixy-cli requires reading each reference in full (line 22) and verifying every applicable rule with evidence (lines 79–81). IO3 already includes the README pointer and retry-guidance requirement. This candidate repeats that rule without a distinct verification operation; the source finding's sole-checklist premise is unsupported. The PR will close without merging.
jercik closed this pull request 2026-10-03 23:57:18 +00:00
All checks were successful
commit-msg / commitlint (pull_request) Successful in 22s
Review / Review (pull_request_target) Successful in 2m34s
Node tests / node:test (pull_request) Successful in 3m4s

Pull request closed

Sign in to join this conversation.
No reviewers
No labels
No milestone
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
j4k-oss/agent-skills!111
No description provided.