fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik · 2026-10-02T07:26:01Z

jercik commented

2026-10-02 07:26:01 +00:00

Points drifted set copies at reader-reachable sources and renders CLI dependency and exit-code help from the code's definitions. Keeps per-tool setup detail, the README fallback until help lists dependencies, and the independent fatal dependency check after help and version handling.

Preserves the binding ADR/user decision rules from current main. The referenced verify-readme guidance is present because #96 has merged.

Points drifted set copies at reader-reachable sources and renders CLI dependency and exit-code help from the code's definitions. Keeps per-tool setup detail, the README fallback until help lists dependencies, and the independent fatal dependency check after help and version handling. Preserves the binding ADR/user decision rules from current main. The referenced `verify-readme` guidance is present because #96 has merged.

jercik added 1 commit

2026-10-02 07:26:01 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets

commit-msg / commitlint (pull_request) Failing after 20s

Details

Node tests / node:test (pull_request) Successful in 2m8s

Details

Review / Review (pull_request_target) Successful in 2m37s

Details

bca5874f6c

verify-unixy-cli's ARG8 asked for a README section listing every external
dependency, and verify-doc-drift corrected a drifted copy of a code-defined
set instead of replacing it with a pointer. Both now point at the source and
keep only the detail it can't show; help output lists dependencies and exit
codes from the code's own table.

jercik changed title from ~~fix(skills): CLI docs and drift fixes should point at sources instead of restating sets~~ to fix(skills): point CLI docs and drift fixes at sources instead of restating sets

2026-10-02 07:27:25 +00:00

forgejo-actions commented

2026-10-02 07:29:59 +00:00

Review 01M42HX6QX34CGE58C3SGMT98A — head e28d807d3be83b91a375c6d6aca88d689aa4d3d5

Review — j4k-oss/agent-skills @ `8d139933be`

Scope: diff against base tree 2034125557e6
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 — ARG8 item 2 restates verify-readme's "Sets defined elsewhere" rule while also pointing at it

claim: 01M42J0ZEAST8BJD0NDNQNBSJZ
anchor: skills/verify-unixy-cli/references/arg8-document-external-dependencies.md (snippet)

2. **Pointed at from the README**: Once help lists them, a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools and adds per-tool installation, authentication, or version guidance where help does not provide it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list, which satisfies this item

lens: writing-quality · arm: default
verdicts: 1 valid / 0 invalid / 0 uncertain
disposition: none

What I examined: ARG8 item 2 (changed in this diff), verify-unixy-cli/SKILL.md frontmatter, and verify-readme/SKILL.md's "Sets defined elsewhere" section.

What the subject says: item 2 now spells out the README rule in full — name --help as the list, add per-tool installation/authentication/version guidance where help lacks it, "without a count or a claim to cover them all" — and then cites verify-readme's "Sets defined elsewhere". That verify-readme section already says the README names the source instead of listing members, adds "the detail the source can't show, for each member that needs it", and "don't introduce it with a count or a claim to cover them all". verify-unixy-cli declares the dependency (axskills.requires: "verify-readme"), and ARG5 calls verify-readme the canonical README contract.

Why it matters: the writing skill's "One Idea, One Place" says to call declared skill dependencies instead of duplicating their instructions. The 60-word item is the longest in the list. It also keeps a second copy of verify-readme's wording, which will drift when verify-readme changes. The copy has already narrowed the rule: verify-readme also covers what a member means and why it exists, but item 2 names only installation, authentication, and version guidance.

Proposed correction: "2. Pointed at from the README: Once help lists them, the README's "Requirements" or "Prerequisites" section points at --help as verify-readme's "Sets defined elsewhere" describes. Until then, a README list satisfies this item." This keeps the item's trigger (help lists them), the fallback (a README list satisfies the item), the section names, and the pointer. The per-tool detail and the no-count rule stay where verify-readme defines them.

What would refute it: if ARG8 is meant to be read without verify-readme loaded. The declared requires and ARG5's deferral show that verify-readme is loaded.

Other claims

grounding-pending (0)
ungrounded (0)
rejected (2)
- 01M42J1DTP1J5EYYPCP6GQED22 low — ARG8 now hands path resolution to ARG9's command records, which make the path env var optional, while ARG8 still requires one for every dependency
- 01M42J1H3KB9JQVGTXE6GTGCZ3 low — verify-doc-drift Task step 5 now reads as if the sibling sweep applies only to restated-set pointers
duplicate-of (0)
unadjudicated (2)
- 01M42J13VKFSQ9K9RB1M26B0GV high — verify-doc-drift restates verify-readme's list of reachable pointer targets and has already dropped "hosted docs URL"
- 01M42J1GMM2DYA6CYT6EX2J1VV low — ARG8 makes ARG9's model mandatory under an undefined term ("command records") after item 1 offered it only as an example

Coverage

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

lens	part	arm	unit status	runs	loss
general-bug	whole	default	claims-emitted	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** `01M42HX6QX34CGE58C3SGMT98A` — head `e28d807d3be83b91a375c6d6aca88d689aa4d3d5` # Review — j4k-oss/agent-skills @ 8d139933be25 Scope: diff against base tree `2034125557e6` 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 — ARG8 item 2 restates verify-readme's "Sets defined elsewhere" rule while also pointing at it - claim: `01M42J0ZEAST8BJD0NDNQNBSJZ` - anchor: `skills/verify-unixy-cli/references/arg8-document-external-dependencies.md` (snippet) ``` 2. **Pointed at from the README**: Once help lists them, a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools and adds per-tool installation, authentication, or version guidance where help does not provide it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list, which satisfies this item ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > What I examined: ARG8 item 2 (changed in this diff), verify-unixy-cli/SKILL.md frontmatter, and verify-readme/SKILL.md's "Sets defined elsewhere" section. > > What the subject says: item 2 now spells out the README rule in full — name `--help` as the list, add per-tool installation/authentication/version guidance where help lacks it, "without a count or a claim to cover them all" — and then cites verify-readme's "Sets defined elsewhere". That verify-readme section already says the README names the source instead of listing members, adds "the detail the source can't show, for each member that needs it", and "don't introduce it with a count or a claim to cover them all". verify-unixy-cli declares the dependency (`axskills.requires: "verify-readme"`), and ARG5 calls verify-readme the canonical README contract. > > Why it matters: the writing skill's "One Idea, One Place" says to call declared skill dependencies instead of duplicating their instructions. The 60-word item is the longest in the list. It also keeps a second copy of verify-readme's wording, which will drift when verify-readme changes. The copy has already narrowed the rule: verify-readme also covers what a member means and why it exists, but item 2 names only installation, authentication, and version guidance. > > Proposed correction: "2. **Pointed at from the README**: Once help lists them, the README's \"Requirements\" or \"Prerequisites\" section points at `--help` as verify-readme's \"Sets defined elsewhere\" describes. Until then, a README list satisfies this item." This keeps the item's trigger (help lists them), the fallback (a README list satisfies the item), the section names, and the pointer. The per-tool detail and the no-count rule stay where verify-readme defines them. > > What would refute it: if ARG8 is meant to be read without verify-readme loaded. The declared `requires` and ARG5's deferral show that verify-readme is loaded. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (2) - `01M42J1DTP1J5EYYPCP6GQED22` low — ARG8 now hands path resolution to ARG9's command records, which make the path env var optional, while ARG8 still requires one for every dependency - `01M42J1H3KB9JQVGTXE6GTGCZ3` low — verify-doc-drift Task step 5 now reads as if the sibling sweep applies only to restated-set pointers - duplicate-of (0) - unadjudicated (2) - `01M42J13VKFSQ9K9RB1M26B0GV` high — verify-doc-drift restates verify-readme's list of reachable pointer targets and has already dropped "hosted docs URL" - `01M42J1GMM2DYA6CYT6EX2J1VV` low — ARG8 makes ARG9's model mandatory under an undefined term ("command records") after item 1 offered it only as an example ## Coverage Coverage pass: 01M42HX6SS3P96ZW6CQP758B7J Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | claims-emitted | 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 |

👀 1

forgejo-actions reviewed

2026-10-02 07:30:00 +00:00

skills/verify-doc-drift/SKILL.md Outdated

					
				@ -38,1 +38,4 @@

				## Restated sets: point instead of recopying

				When drifted text restates a set the code defines — it lists every member, or states how many there are, of a set that a file, directory, schema, or command defines, such as the flags `--help` prints or the keys a config schema declares — the fix replaces the copy with a pointer to that source. Correcting the copy only restarts the clock on the next drift. Name a source the doc's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path. Keep the per-member detail the source can't show — what a member means, why it exists, its traps, which members the reader must set when the source doesn't mark them — for the members that need it, without a count or a claim to cover them all, even when every member needs it. Correct the list in place where no pointer can replace it, such as in a dated record that misstates current behaviour, a contract the doc's reader can't see anywhere else, or a number that is the subject of an argument rather than the size of a set. Regenerate a section generated from the source instead of editing it.

low — verify-doc-drift's "Restated sets" section hides its directive and exceptions inside one dense paragraph
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: the new "Restated sets: point instead of recopying" section of skills/verify-doc-drift/SKILL.md, read alongside the surrounding Reference sections and Task step 5, which now says to "point a drifted restated set at its source".

What the subject says: the section's first sentence is about 60 words long. Before the reader reaches the instruction ("the fix replaces the copy with a pointer to that source"), it passes through an em-dash aside that defines "restates" and then gives examples of the defining source. The section is a single paragraph of six sentences. Several are just as dense, e.g. "Keep the per-member detail the source can't show — what a member means, why it exists, its traps, which members the reader must set when the source doesn't mark them — for the members that need it, without a count or a claim to cover them all, even when every member needs it." That one sentence holds four kinds of detail and two qualifiers. "a claim to cover them all" is never defined; ARG8 sends readers to a verify-readme section that does not exist for its meaning.

What goes wrong: the writing-for-agents skill says "Lead with the action and its object; attach conditions to the action they govern", "Group by concept", and "use plain prose by default, bullets for flat choices". An auditing agent has to decide between three outcomes: point at the source, keep per-member detail, or correct in place. All three are buried in one block. That makes it easy to miss the in-place exceptions (dated records, contracts the reader can't see elsewhere, a number that is the subject of an argument). It's also easy to misread "without a count or a claim to cover them all" as a ban on any per-member detail.

Proposed correction: lead with the action, then define the trigger and list the exceptions separately. For example:
"Replace a drifted restated set with a pointer to the source that defines it. A doc restates a set when it lists every member, or gives the count, of a set a file, directory, schema, or command defines (the flags --help prints, the keys a config schema declares)."
Then a short paragraph on which pointer target the reader can reach, one sentence on keeping per-member detail ("Keep what the source can't show for the members that need it, but don't give a count or call the list complete"), and a bulleted list of the correct-in-place exceptions. This keeps every rule in the current text, including the regenerate-generated-sections rule, and makes the action and its exceptions visible.

Basis: static reading against the installed writing-for-agents guidance. I did not test agent behaviour.

claim 01M3XR6RTAVY29PMMFBFGAFF7R of review 01M3XR32DQG1FSJV28PNWFQ7RV

**low** — verify-doc-drift's "Restated sets" section hides its directive and exceptions inside one dense paragraph lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: the new "Restated sets: point instead of recopying" section of skills/verify-doc-drift/SKILL.md, read alongside the surrounding Reference sections and Task step 5, which now says to "point a drifted restated set at its source". > > What the subject says: the section's first sentence is about 60 words long. Before the reader reaches the instruction ("the fix replaces the copy with a pointer to that source"), it passes through an em-dash aside that defines "restates" and then gives examples of the defining source. The section is a single paragraph of six sentences. Several are just as dense, e.g. "Keep the per-member detail the source can't show — what a member means, why it exists, its traps, which members the reader must set when the source doesn't mark them — for the members that need it, without a count or a claim to cover them all, even when every member needs it." That one sentence holds four kinds of detail and two qualifiers. "a claim to cover them all" is never defined; ARG8 sends readers to a verify-readme section that does not exist for its meaning. > > What goes wrong: the writing-for-agents skill says "Lead with the action and its object; attach conditions to the action they govern", "Group by concept", and "use plain prose by default, bullets for flat choices". An auditing agent has to decide between three outcomes: point at the source, keep per-member detail, or correct in place. All three are buried in one block. That makes it easy to miss the in-place exceptions (dated records, contracts the reader can't see elsewhere, a number that is the subject of an argument). It's also easy to misread "without a count or a claim to cover them all" as a ban on any per-member detail. > > Proposed correction: lead with the action, then define the trigger and list the exceptions separately. For example: > "Replace a drifted restated set with a pointer to the source that defines it. A doc restates a set when it lists every member, or gives the count, of a set a file, directory, schema, or command defines (the flags `--help` prints, the keys a config schema declares)." > Then a short paragraph on which pointer target the reader can reach, one sentence on keeping per-member detail ("Keep what the source can't show for the members that need it, but don't give a count or call the list complete"), and a bulleted list of the correct-in-place exceptions. This keeps every rule in the current text, including the regenerate-generated-sections rule, and makes the action and its exceptions visible. > > Basis: static reading against the installed writing-for-agents guidance. I did not test agent behaviour. > claim `01M3XR6RTAVY29PMMFBFGAFF7R` of review `01M3XR32DQG1FSJV28PNWFQ7RV`

👍 1

superseded by review 01M3XWQJQHWPCMKQV9PJA6MW4T for head 32ff203472fd2cebc14846635f93517f1c44eb29

superseded by review `01M3XWQJQHWPCMKQV9PJA6MW4T` for head `32ff203472fd2cebc14846635f93517f1c44eb29`

🚀 1

Fixed in 8aecabf: the section now leads with the action, then gives the pointer target, the kept detail, and a bulleted list of the in-place exceptions, each in its own paragraph.

Fixed in 8aecabf: the section now leads with the action, then gives the pointer target, the kept detail, and a bulleted list of the in-place exceptions, each in its own paragraph.

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -4,3 +4,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Pointed at from the README**: Once help lists them (item 2), a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools, then adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and item 2 is reported as failing

medium — ARG8 cites verify-readme's "Sets defined elsewhere" section, which does not exist; verify-readme's Requirements guidance still says to list the binaries
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: the changed ARG8 rule (skills/verify-unixy-cli/references/arg8-document-external-dependencies.md), all of skills/verify-readme/SKILL.md (its only file), and a tree-wide grep for "Sets defined elsewhere" / "defined elsewhere".

What the subject says: ARG8 item 1 now tells the auditor that the README's Requirements section should name --help as the list of external tools "without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere")". The grep matches only this ARG8 line. verify-readme/SKILL.md has no such heading; its headings are Inputs, Reference, Section order (1–9), package.json#description parity, One-liner test, Pipeline patterns, Agent Rule template, Task, Output. Its "### 7. Requirements" section says the opposite of the new rule: "Include only when a requirement isn't implied by Quick Start (specific Node floor, external binaries like git / gh, auth setup, OS constraints)". Nothing there says to point at --help instead of listing the binaries. ARG5 (arg5-readme-quality.md) calls verify-readme "the canonical README contract".

What goes wrong: an agent applying ARG8 follows the cross-reference to get the full rule and finds nothing. The README skill that ARG5 calls canonical still tells it to disclose the binaries in Requirements. A CLI README audited by verify-readme and by verify-unixy-cli therefore gets conflicting instructions: list git/gh versus point at --help and don't restate the list. It looks like the companion verify-readme edit that adds the section was left out of this change. The closest real text is verify-doc-drift's new "Restated sets: point instead of recopying" section.

How to confirm or refute: grep -rn "Sets defined elsewhere" skills/ returns only the ARG8 line. The fix is either to add the section to verify-readme/SKILL.md and update its Requirements guidance to match, or to point the reference at verify-doc-drift's "Restated sets" section.

claim 01M3XR55GVPZ2WNXF4MSZW7RGB of review 01M3XR32DQG1FSJV28PNWFQ7RV

**medium** — ARG8 cites verify-readme's "Sets defined elsewhere" section, which does not exist; verify-readme's Requirements guidance still says to list the binaries lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: the changed ARG8 rule (skills/verify-unixy-cli/references/arg8-document-external-dependencies.md), all of skills/verify-readme/SKILL.md (its only file), and a tree-wide grep for "Sets defined elsewhere" / "defined elsewhere". > > What the subject says: ARG8 item 1 now tells the auditor that the README's Requirements section should name `--help` as the list of external tools "without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere")". The grep matches only this ARG8 line. verify-readme/SKILL.md has no such heading; its headings are Inputs, Reference, Section order (1–9), `package.json#description` parity, One-liner test, Pipeline patterns, Agent Rule template, Task, Output. Its "### 7. Requirements" section says the opposite of the new rule: "Include only when a requirement isn't implied by Quick Start (specific Node floor, external binaries like `git` / `gh`, auth setup, OS constraints)". Nothing there says to point at `--help` instead of listing the binaries. ARG5 (arg5-readme-quality.md) calls verify-readme "the canonical README contract". > > What goes wrong: an agent applying ARG8 follows the cross-reference to get the full rule and finds nothing. The README skill that ARG5 calls canonical still tells it to disclose the binaries in Requirements. A CLI README audited by verify-readme and by verify-unixy-cli therefore gets conflicting instructions: list `git`/`gh` versus point at `--help` and don't restate the list. It looks like the companion verify-readme edit that adds the section was left out of this change. The closest real text is verify-doc-drift's new "Restated sets: point instead of recopying" section. > > How to confirm or refute: `grep -rn "Sets defined elsewhere" skills/` returns only the ARG8 line. The fix is either to add the section to verify-readme/SKILL.md and update its Requirements guidance to match, or to point the reference at verify-doc-drift's "Restated sets" section. claim `01M3XR55GVPZ2WNXF4MSZW7RGB` of review `01M3XR32DQG1FSJV28PNWFQ7RV`

👎 1

low — ARG8 item 1 depends on item 2 and packs five rules into one list item; put the help requirement first
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: the numbered requirement list in the changed ARG8 reference (skills/verify-unixy-cli/references/arg8-document-external-dependencies.md).

What the subject says: item 1 is now a single item of about 70 words. Its rule depends on item 2: "Once help lists them (item 2) ... Until then, the README keeps its list and item 2 is reported as failing". Item 2 ("Listed in help output: Rendered from the same list the startup check reads ...") is the prerequisite but comes second. Items 3 and 4 are each one short line.

What goes wrong: the reader evaluates item 1 before learning what item 2 requires, so they have to read ahead and come back to apply it. The writing-for-agents skill says "Order sections by the decisions the reader makes" and "Group by concept: keep a term's definition, rule, and caveat together". Here the README rule comes before the help rule it depends on, and item 1 packs the pointer rule, the per-tool detail rule, the no-count rule, a cross-reference, and the fallback into one list item.

Proposed correction: swap the first two items so "Listed in help output" comes first. Then shorten the README item to the rule and its fallback, e.g. "Pointed at from the README: when help lists the tools (item 1), the Requirements section names --help as the list and adds only what help can't show (install steps, version floors, auth setup) for the tools that need it. Until then, the README keeps its own list." This keeps every requirement and the transitional case, and lets the reader check the items in order.

Basis: static reading; nothing was executed.

claim 01M3XR73SASM8SPDB5NBCG4P1D of review 01M3XR32DQG1FSJV28PNWFQ7RV

**low** — ARG8 item 1 depends on item 2 and packs five rules into one list item; put the help requirement first lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: the numbered requirement list in the changed ARG8 reference (skills/verify-unixy-cli/references/arg8-document-external-dependencies.md). > > What the subject says: item 1 is now a single item of about 70 words. Its rule depends on item 2: "Once help lists them (item 2) ... Until then, the README keeps its list and item 2 is reported as failing". Item 2 ("Listed in help output: Rendered from the same list the startup check reads ...") is the prerequisite but comes second. Items 3 and 4 are each one short line. > > What goes wrong: the reader evaluates item 1 before learning what item 2 requires, so they have to read ahead and come back to apply it. The writing-for-agents skill says "Order sections by the decisions the reader makes" and "Group by concept: keep a term's definition, rule, and caveat together". Here the README rule comes before the help rule it depends on, and item 1 packs the pointer rule, the per-tool detail rule, the no-count rule, a cross-reference, and the fallback into one list item. > > Proposed correction: swap the first two items so "Listed in help output" comes first. Then shorten the README item to the rule and its fallback, e.g. "Pointed at from the README: when help lists the tools (item 1), the Requirements section names `--help` as the list and adds only what help can't show (install steps, version floors, auth setup) for the tools that need it. Until then, the README keeps its own list." This keeps every requirement and the transitional case, and lets the reader check the items in order. > > Basis: static reading; nothing was executed. > claim `01M3XR73SASM8SPDB5NBCG4P1D` of review `01M3XR32DQG1FSJV28PNWFQ7RV`

👍 1

superseded by review 01M3XWQJQHWPCMKQV9PJA6MW4T for head 32ff203472fd2cebc14846635f93517f1c44eb29

superseded by review `01M3XWQJQHWPCMKQV9PJA6MW4T` for head `32ff203472fd2cebc14846635f93517f1c44eb29`

🚀 1

Fixed in 8aecabf: help output is item 1 and the README pointer is item 2, which now opens with "Once help lists them" and ends with "Until then, the README keeps its list and only item 1 fails".

Fixed in 8aecabf: help output is item 1 and the README pointer is item 2, which now opens with "Once help lists them" and ends with "Until then, the README keeps its list and only item 1 fails".

The section comes from #96, which adds "## Sets defined elsewhere" to verify-readme/SKILL.md (origin/fix/verify-readme-point-to-sources). This PR's body says to merge it after #96, so the reference resolves once both land. On #96, that section names --help as a source to point at, and the Requirements rule only says when the README discloses external binaries, not to list them. 8aecabf also drops ARG8's own Requirements-section wording, so ARG8 no longer depends on that rule's text.

The section comes from #96, which adds "## Sets defined elsewhere" to verify-readme/SKILL.md (origin/fix/verify-readme-point-to-sources). This PR's body says to merge it after #96, so the reference resolves once both land. On #96, that section names --help as a source to point at, and the Requirements rule only says when the README discloses external binaries, not to list them. 8aecabf also drops ARG8's own Requirements-section wording, so ARG8 no longer depends on that rule's text.

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -29,3 +29,3 @@

				- Search for `exec`, `execSync`, `spawn`, `spawnSync`, `execa`, or `child_process` usage to identify external dependencies

				- Check README for a "Requirements" section and `--help` for dependency mentions

				- Check that `--help` lists each dependency from the list the startup check reads, and that the README's "Requirements" section points at `--help` rather than restating the list

low — ARG8's "How to verify" requires the README to point at --help unconditionally, contradicting item 1's rule that the README keeps its list until help lists the tools
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: the whole of the changed ARG8 rule file, comparing the rewritten item 1 with the rewritten "How to verify" bullet.

What the subject says: item 1 makes the README pointer conditional. "Once help lists them (item 2), a "Requirements" or "Prerequisites" section names --help as the list ... Until then, the README keeps its list and item 2 is reported as failing". The verification bullet that an auditor actually runs has no such condition: "Check that --help lists each dependency ..., and that the README's "Requirements" section points at --help rather than restating the list".

What goes wrong: take a CLI whose --help does not list its external tools yet, and whose README correctly lists them. Under item 1 that README is compliant and only item 2 should fail. An agent working from the How-to-verify checklist will also flag the README for "restating the list" and may tell the user to replace it with a pointer to --help. That --help output does not contain the list, so the user loses the only place the dependencies were documented. This is the exact outcome item 1's "Until then" clause was written to prevent. This comes from reading the text side by side; I did not run the skill.

Fix: make the bullet conditional too, e.g. "... and, once it does, that the README's Requirements section points at --help rather than restating the list".

claim 01M3XR5NNXF1QTJMM2MJ52ZFPZ of review 01M3XR32DQG1FSJV28PNWFQ7RV

**low** — ARG8's "How to verify" requires the README to point at --help unconditionally, contradicting item 1's rule that the README keeps its list until help lists the tools lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: the whole of the changed ARG8 rule file, comparing the rewritten item 1 with the rewritten "How to verify" bullet. > > What the subject says: item 1 makes the README pointer conditional. "Once help lists them (item 2), a \"Requirements\" or \"Prerequisites\" section names `--help` as the list ... Until then, the README keeps its list and item 2 is reported as failing". The verification bullet that an auditor actually runs has no such condition: "Check that `--help` lists each dependency ..., and that the README's \"Requirements\" section points at `--help` rather than restating the list". > > What goes wrong: take a CLI whose `--help` does not list its external tools yet, and whose README correctly lists them. Under item 1 that README is compliant and only item 2 should fail. An agent working from the How-to-verify checklist will also flag the README for "restating the list" and may tell the user to replace it with a pointer to `--help`. That `--help` output does not contain the list, so the user loses the only place the dependencies were documented. This is the exact outcome item 1's "Until then" clause was written to prevent. This comes from reading the text side by side; I did not run the skill. > > Fix: make the bullet conditional too, e.g. "... and, once it does, that the README's Requirements section points at `--help` rather than restating the list". claim `01M3XR5NNXF1QTJMM2MJ52ZFPZ` of review `01M3XR32DQG1FSJV28PNWFQ7RV`

👍 1

superseded by review 01M3XWQJQHWPCMKQV9PJA6MW4T for head 32ff203472fd2cebc14846635f93517f1c44eb29

superseded by review `01M3XWQJQHWPCMKQV9PJA6MW4T` for head `32ff203472fd2cebc14846635f93517f1c44eb29`

🚀 1

Fixed in 8aecabf: the How to verify bullet now checks the README pointer only once help lists the tools.

Fixed in 8aecabf: the How to verify bullet now checks the README pointer only once help lists the tools.

jercik marked this conversation as resolved

jercik referenced this pull request

2026-10-02 08:29:07 +00:00

fix(skills): route skill references by their own headings instead of copied indexes #99

jercik added 1 commit

2026-10-02 08:47:07 +00:00

fix(skills): correct a drifted table of contents in place instead of pointing at its source

commit-msg / commitlint (pull_request) Successful in 28s

Details

Node tests / node:test (pull_request) Successful in 2m6s

Details

Review / Review (pull_request_target) Successful in 27m43s

Details

32ff203472

forgejo-actions reviewed

2026-10-02 09:14:59 +00:00

skills/verify-doc-drift/SKILL.md Outdated

					
				@ -38,1 +38,4 @@

				## Restated sets: point instead of recopying

				When drifted text restates a set the code defines — it lists every member, or states how many there are, of a set that a file, directory, schema, or command defines, such as the flags `--help` prints or the keys a config schema declares — the fix replaces the copy with a pointer to that source. Correcting the copy only restarts the clock on the next drift. Name a source the doc's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path. Keep the per-member detail the source can't show — what a member means, why it exists, its traps, which members the reader must set when the source doesn't mark them — for the members that need it, without a count or a claim to cover them all, even when every member needs it. Correct the copy in place where no pointer can replace it: a table of contents whose entries each say what an item covers, so the reader can choose which item to open before opening any of them; a dated record that misstates current behaviour; a contract the doc's reader can't see anywhere else; or a number that is the subject of an argument rather than the size of a set. Regenerate a section generated from the source instead of editing it.

medium — Set replacement rule conflicts with the required small-library API reference
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the new Restated sets section in verify-doc-drift/SKILL.md and the CLI/Library Usage rules in verify-readme/SKILL.md. For a small library README that lists every exported API and has one stale entry, this sentence directs the auditor to replace that list with a pointer to code, and the following sentence forbids a claim that the retained per-member details cover all members. Verify-readme instead requires an exhaustive API reference in the README for small libraries and says never to document the surface partially. A reachable source file is not itself a reader-facing API reference or usage explanation, so following the new direction can remove the reference another skill requires. The exception for a contract the reader cannot see elsewhere does not say whether a public source file counts as the contract, leaving the agent with opposing instructions. Explicitly exempt the required small-library API reference from pointer replacement and correct or regenerate it, or change the verify-readme requirement deliberately. That preserves complete API guidance for readers while still using source pointers for copied enumerations whose completeness is better checked at the source. This is a static conflict between the two skill texts; I did not run a library audit.

claim 01M3XY6RWWGPTHQ6SHSF83E5TK of review 01M3XWQJQHWPCMKQV9PJA6MW4T

**medium** — Set replacement rule conflicts with the required small-library API reference lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the new Restated sets section in verify-doc-drift/SKILL.md and the CLI/Library Usage rules in verify-readme/SKILL.md. For a small library README that lists every exported API and has one stale entry, this sentence directs the auditor to replace that list with a pointer to code, and the following sentence forbids a claim that the retained per-member details cover all members. Verify-readme instead requires an exhaustive API reference in the README for small libraries and says never to document the surface partially. A reachable source file is not itself a reader-facing API reference or usage explanation, so following the new direction can remove the reference another skill requires. The exception for a contract the reader cannot see elsewhere does not say whether a public source file counts as the contract, leaving the agent with opposing instructions. Explicitly exempt the required small-library API reference from pointer replacement and correct or regenerate it, or change the verify-readme requirement deliberately. That preserves complete API guidance for readers while still using source pointers for copied enumerations whose completeness is better checked at the source. This is a static conflict between the two skill texts; I did not run a library audit. claim `01M3XY6RWWGPTHQ6SHSF83E5TK` of review `01M3XWQJQHWPCMKQV9PJA6MW4T`

👎 1

#96 changes the verify-readme requirement on purpose, which is the second fix this finding suggests. It replaces "Small surface: exhaustive reference in-README ... Never partially document" with "Point at the type declarations or generated docs (TypeDoc, etc.) for the full API", and this PR merges after #96. With both merged, the skills agree. Exempting an exhaustive in-README API list would also go against the owner's decision that prose restating a set defined elsewhere is a defect to fix by pointing at the source. A public source file the reader can reach counts as a source, per the rule's "a file the published package ships" target.

#96 changes the verify-readme requirement on purpose, which is the second fix this finding suggests. It replaces "Small surface: exhaustive reference in-README ... Never partially document" with "Point at the type declarations or generated docs (TypeDoc, etc.) for the full API", and this PR merges after #96. With both merged, the skills agree. Exempting an exhaustive in-README API list would also go against the owner's decision that prose restating a set defined elsewhere is a defect to fix by pointing at the source. A public source file the reader can reach counts as a source, per the rule's "a file the published package ships" target.

superseded by review 01M3YEB66XJRH2GJ5W1KV738VA for head 8aecabfca014d9571607fe0be0c213d290b7c62d

superseded by review `01M3YEB66XJRH2GJ5W1KV738VA` for head `8aecabfca014d9571607fe0be0c213d290b7c62d`

🚀 1

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -4,3 +4,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Pointed at from the README**: Once help lists them (item 2), a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools, then adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and item 2 is reported as failing

low — ARG8 points readers to a nonexistent verify-readme section
lens general-bug · arm default · tally 2 valid / 0 invalid / 0 uncertain

I read ARG8 and the complete skills/verify-readme/SKILL.md, which ARG8 names as the source for its README rule. ARG8 directs readers to verify-readme's "Sets defined elsewhere", but that skill has no such heading or rule; its CLI Usage guidance addresses flag tables and its Requirements section only says to disclose prerequisites. A reviewer trying to apply the new dependency-list rule cannot find the promised canonical explanation, and may report an inconsistent README requirement. The complete verify-readme file or adding the named section would establish or refute this; in the subject tree, a repository-wide search for the title finds only this ARG8 reference. Update the cross-reference to an existing section or add the missing rule to verify-readme.

claim 01M3XWZV1G1W10NM0QSQ5AFSPB of review 01M3XWQJQHWPCMKQV9PJA6MW4T

**low** — ARG8 points readers to a nonexistent verify-readme section lens `general-bug` · arm `default` · tally 2 valid / 0 invalid / 0 uncertain > I read ARG8 and the complete skills/verify-readme/SKILL.md, which ARG8 names as the source for its README rule. ARG8 directs readers to verify-readme's "Sets defined elsewhere", but that skill has no such heading or rule; its CLI Usage guidance addresses flag tables and its Requirements section only says to disclose prerequisites. A reviewer trying to apply the new dependency-list rule cannot find the promised canonical explanation, and may report an inconsistent README requirement. The complete verify-readme file or adding the named section would establish or refute this; in the subject tree, a repository-wide search for the title finds only this ARG8 reference. Update the cross-reference to an existing section or add the missing rule to verify-readme. claim `01M3XWZV1G1W10NM0QSQ5AFSPB` of review `01M3XWQJQHWPCMKQV9PJA6MW4T`

👎 1

low — ARG8 requires a Requirements section that verify-readme says to omit
lens general-bug · arm default · tally 2 valid / 0 invalid / 0 uncertain

I read ARG8, ARG5 (which calls verify-readme the canonical README contract), and the complete verify-readme skill. ARG8 makes a Requirements or Prerequisites section mandatory for every CLI with external tool dependencies. Verify-readme's Requirements rule instead says to include that section only when a prerequisite is not already implied by Quick Start, and to skip it otherwise. For a CLI whose Quick Start already shows its external tool prerequisite, the same README is required to have the section by ARG8 and required to omit it by the canonical README guidance. This can produce contradictory audit findings or unnecessary edits. The conflict is static in these two rules; the boundary case is a Quick Start that explicitly shows the required external tool. Qualify ARG8's section requirement for that case, or reconcile the canonical Requirements rule.

claim 01M3XX38YTNZV806FF2KZ8RZDB of review 01M3XWQJQHWPCMKQV9PJA6MW4T

**low** — ARG8 requires a Requirements section that verify-readme says to omit lens `general-bug` · arm `default` · tally 2 valid / 0 invalid / 0 uncertain > I read ARG8, ARG5 (which calls verify-readme the canonical README contract), and the complete verify-readme skill. ARG8 makes a Requirements or Prerequisites section mandatory for every CLI with external tool dependencies. Verify-readme's Requirements rule instead says to include that section only when a prerequisite is not already implied by Quick Start, and to skip it otherwise. For a CLI whose Quick Start already shows its external tool prerequisite, the same README is required to have the section by ARG8 and required to omit it by the canonical README guidance. This can produce contradictory audit findings or unnecessary edits. The conflict is static in these two rules; the boundary case is a Quick Start that explicitly shows the required external tool. Qualify ARG8's section requirement for that case, or reconcile the canonical Requirements rule. claim `01M3XX38YTNZV806FF2KZ8RZDB` of review `01M3XWQJQHWPCMKQV9PJA6MW4T`

👍 1

Fixed in 8aecabf: ARG8 no longer requires a Requirements or Prerequisites section. It asks only that the README name --help as the list once help lists the tools, so verify-readme's Requirements rule decides whether the README has that section.

Fixed in 8aecabf: ARG8 no longer requires a Requirements or Prerequisites section. It asks only that the README name --help as the list once help lists the tools, so verify-readme's Requirements rule decides whether the README has that section.

Same as the earlier finding on this line: #96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land.

Same as the earlier finding on this line: #96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land.

superseded by review 01M3YEB66XJRH2GJ5W1KV738VA for head 8aecabfca014d9571607fe0be0c213d290b7c62d

superseded by review `01M3YEB66XJRH2GJ5W1KV738VA` for head `8aecabfca014d9571607fe0be0c213d290b7c62d`

🚀 1

jercik added 1 commit

2026-10-02 13:54:57 +00:00

fix(skills): order arg8 by dependency and split the restated-sets rule into steps

commit-msg / commitlint (pull_request) Successful in 16s

Details

Node tests / node:test (pull_request) Successful in 1m7s

Details

Review / Review (pull_request_target) Successful in 8m40s

Details

8aecabfca0

List the help requirement before the README pointer that depends on it,
make the README check conditional on help listing the tools, and leave
README section placement to verify-readme. Split verify-doc-drift's
restated-sets paragraph into the action, the pointer target, the kept
detail, and a list of in-place exceptions.

forgejo-actions reviewed

2026-10-02 14:03:35 +00:00

skills/verify-doc-drift/SKILL.md Outdated

					
				@ -38,1 +38,4 @@

				## Restated sets: point instead of recopying

				Replace drifted text that restates a set the code defines with a pointer to the source that defines it; correcting the copy only restarts the clock on the next drift. Text restates a set when it lists every member, or states how many there are, of a set that a file, directory, schema, or command defines, such as the flags `--help` prints or the keys a config schema declares.

medium — Set replacement rule removes required small-library API references
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the new 'Restated sets' section against verify-readme's Usage/API contract. This instruction applies to any drifted text listing every member of a code-defined set. A small library's README API reference is exactly such a set of exported methods, but verify-readme explicitly requires 'Small surface: exhaustive reference in-README.' When an export changes, the doc-drift skill would replace that reference with a source pointer while the README skill would restore it, and users lose the self-contained reference that verify-readme requires. The writing standard says related skills should have one clear instruction and explicit boundaries. Add an exception for a reader-facing reference that is the intended contract, or say to regenerate it from the code when possible; keep the rule for redundant inventories such as copied flag tables. This is a static conflict between two subject skills; I did not test a model applying them together.

claim 01M3YEKZBMCS3YQ9KFJB5NDR3D of review 01M3YEB66XJRH2GJ5W1KV738VA

**medium** — Set replacement rule removes required small-library API references lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the new 'Restated sets' section against verify-readme's Usage/API contract. This instruction applies to any drifted text listing every member of a code-defined set. A small library's README API reference is exactly such a set of exported methods, but verify-readme explicitly requires 'Small surface: exhaustive reference in-README.' When an export changes, the doc-drift skill would replace that reference with a source pointer while the README skill would restore it, and users lose the self-contained reference that verify-readme requires. The writing standard says related skills should have one clear instruction and explicit boundaries. Add an exception for a reader-facing reference that is the intended contract, or say to regenerate it from the code when possible; keep the rule for redundant inventories such as copied flag tables. This is a static conflict between two subject skills; I did not test a model applying them together. claim `01M3YEKZBMCS3YQ9KFJB5NDR3D` of review `01M3YEB66XJRH2GJ5W1KV738VA`

👎 1

Same as the earlier finding on this section: #96 changes verify-readme's Library rule on purpose to "Point at the type declarations or generated docs (TypeDoc, etc.) for the full API", which removes the in-README exhaustive reference. This PR merges after #96, so the two skills agree once both land. An exception for an exhaustive in-README API list would go against the owner's decision that prose restating a set defined elsewhere is a defect to fix by pointing at the source.

Same as the earlier finding on this section: #96 changes verify-readme's Library rule on purpose to "Point at the type declarations or generated docs (TypeDoc, etc.) for the full API", which removes the in-README exhaustive reference. This PR merges after #96, so the two skills agree once both land. An exception for an exhaustive in-README API list would go against the owner's decision that prose restating a set defined elsewhere is a defect to fix by pointing at the source.

superseded by review 01M3YF2CB2260ZYAF6S0VNZ8GH for head 454abc298c089a0938e9f7a07d193b8aa1f7f682

superseded by review `01M3YF2CB2260ZYAF6S0VNZ8GH` for head `454abc298c089a0938e9f7a07d193b8aa1f7f682`

🚀 1

skills/verify-doc-drift/SKILL.md Outdated

					
				@ -39,0 +47,4 @@

				Correct the copy in place instead where no pointer can replace it:

				- a table of contents whose entries each say what an item covers, so the reader can choose which item to open before opening any of them

				- a dated record, such as a changelog entry or release note, that misstates current behaviour

medium — Judge dated release records against their release, not current code
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the new 'Restated sets' section in verify-doc-drift and its surrounding audit loop. The exception says to correct a changelog entry or release note in place when it 'misstates current behaviour.' A dated note describes what shipped at its own release; after a later release changes a flag or config key, an accurate old note can differ from current code. Following this wording would make an auditor rewrite release history to match today's interface, misleading readers investigating an older version. The writing standard calls for durable, verifiable claims scoped to the version they describe. Say to correct a dated record only when it inaccurately describes its own release, and to verify that against release-specific evidence; a mismatch with the current tree alone is insufficient. I could not inspect earlier releases in this snapshot, so the claim concerns the instruction's decision rule, not a particular changelog entry.

claim 01M3YEHNBFMXZ1PYE63YC6X1G3 of review 01M3YEB66XJRH2GJ5W1KV738VA

**medium** — Judge dated release records against their release, not current code lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the new 'Restated sets' section in verify-doc-drift and its surrounding audit loop. The exception says to correct a changelog entry or release note in place when it 'misstates current behaviour.' A dated note describes what shipped at its own release; after a later release changes a flag or config key, an accurate old note can differ from current code. Following this wording would make an auditor rewrite release history to match today's interface, misleading readers investigating an older version. The writing standard calls for durable, verifiable claims scoped to the version they describe. Say to correct a dated record only when it inaccurately describes its own release, and to verify that against release-specific evidence; a mismatch with the current tree alone is insufficient. I could not inspect earlier releases in this snapshot, so the claim concerns the instruction's decision rule, not a particular changelog entry. claim `01M3YEHNBFMXZ1PYE63YC6X1G3` of review `01M3YEB66XJRH2GJ5W1KV738VA`

👍 1

Fixed in 454abc2: the exception now reads "a dated record, such as a changelog entry or release note, that misstates the release it describes; a difference from the current code alone is not drift".

Fixed in 454abc2: the exception now reads "a dated record, such as a changelog entry or release note, that misstates the release it describes; a difference from the current code alone is not drift".

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -5,2 +5,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code

**Pointed at from the README**: Once help lists them, the README names `--help` as the list of these external tools and adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and only item 1 fails

low — ARG8 sends readers to a nonexistent verify-readme section
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read ARG8, verify-readme/SKILL.md, verify-unixy-cli/SKILL.md, and ARG5. ARG8 tells the auditor to see verify-readme's “Sets defined elsewhere” for how to document external tools, but verify-readme has no section or wording by that name; a tree search finds the phrase only in ARG8. Its Requirements section still says to include non-obvious external binaries, while its CLI Usage section only points to --help for flags. An auditor following the new cross-reference cannot find the rule that is supposed to explain the new README behavior, and the two skills give different instructions about dependency lists. Add the referenced section to verify-readme or replace the reference with a valid rule and reconcile its Requirements guidance. This is a static documentation check; the existence of a matching section in verify-readme would refute it.

claim 01M3YEGRVAQJPFZK9SF1Y4F299 of review 01M3YEB66XJRH2GJ5W1KV738VA

**low** — ARG8 sends readers to a nonexistent verify-readme section lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read ARG8, verify-readme/SKILL.md, verify-unixy-cli/SKILL.md, and ARG5. ARG8 tells the auditor to see verify-readme's “Sets defined elsewhere” for how to document external tools, but verify-readme has no section or wording by that name; a tree search finds the phrase only in ARG8. Its Requirements section still says to include non-obvious external binaries, while its CLI Usage section only points to --help for flags. An auditor following the new cross-reference cannot find the rule that is supposed to explain the new README behavior, and the two skills give different instructions about dependency lists. Add the referenced section to verify-readme or replace the reference with a valid rule and reconcile its Requirements guidance. This is a static documentation check; the existence of a matching section in verify-readme would refute it. claim `01M3YEGRVAQJPFZK9SF1Y4F299` of review `01M3YEB66XJRH2GJ5W1KV738VA`

👎 1

#96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land. That section is also where verify-readme reconciles its Requirements guidance with pointing at --help.

#96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land. That section is also where verify-readme reconciles its Requirements guidance with pointing at --help.

superseded by review 01M3YF2CB2260ZYAF6S0VNZ8GH for head 454abc298c089a0938e9f7a07d193b8aa1f7f682

superseded by review `01M3YF2CB2260ZYAF6S0VNZ8GH` for head `454abc298c089a0938e9f7a07d193b8aa1f7f682`

🚀 1

jercik added 1 commit

2026-10-02 14:07:37 +00:00

fix(verify-doc-drift): judge a dated record against its own release

commit-msg / commitlint (pull_request) Successful in 14s

Details

Node tests / node:test (pull_request) Successful in 1m2s

Details

Review / Review (pull_request_target) Successful in 11m41s

Details

454abc298c

A changelog entry or release note describes the release it belongs to,
so a difference from the current code alone is not drift to correct.

forgejo-actions reviewed

2026-10-02 14:19:17 +00:00

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -5,2 +5,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code

**Pointed at from the README**: Once help lists them, the README names `--help` as the list of these external tools and adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and only item 1 fails

low — ARG8 points to a nonexistent verify-readme section
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read ARG8, verify-unixy-cli/SKILL.md, and the full skills/verify-readme/SKILL.md. ARG8 tells an auditor to follow verify-readme's "Sets defined elsewhere" guidance when replacing a README dependency list with a pointer to --help. The referenced skill has no section or phrase with that name; its Requirements section instead says to include non-obvious prerequisites, including external binaries. Thus an auditor cannot follow the cited rule or resolve whether a pointer alone satisfies the README contract, and may produce inconsistent dependency documentation. This is a static documentation check. The decisive correction is to add the referenced section to verify-readme or change ARG8 to point to existing guidance and reconcile the Requirements rule.

claim 01M3YFA2E7K2BRCXRPSYQZPXQH of review 01M3YF2CB2260ZYAF6S0VNZ8GH

**low** — ARG8 points to a nonexistent verify-readme section lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read ARG8, verify-unixy-cli/SKILL.md, and the full skills/verify-readme/SKILL.md. ARG8 tells an auditor to follow verify-readme's "Sets defined elsewhere" guidance when replacing a README dependency list with a pointer to --help. The referenced skill has no section or phrase with that name; its Requirements section instead says to include non-obvious prerequisites, including external binaries. Thus an auditor cannot follow the cited rule or resolve whether a pointer alone satisfies the README contract, and may produce inconsistent dependency documentation. This is a static documentation check. The decisive correction is to add the referenced section to verify-readme or change ARG8 to point to existing guidance and reconcile the Requirements rule. claim `01M3YFA2E7K2BRCXRPSYQZPXQH` of review `01M3YF2CB2260ZYAF6S0VNZ8GH`

👎 1

low — ARG8's fallback says only one check fails even when others may fail
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the complete ARG8 checklist and its How to verify bullets. Item 3 independently requires an environment variable for each dependency, and item 4 independently requires a startup check. The new fallback for a CLI whose --help does not list dependencies says only item 1 fails. For a CLI that also has no path override or startup check, that sentence literally marks just item 1 as failed and can hide failures of items 3 and 4 in the audit report. The writing standard asks for verifiable claims and conditions attached to the action they govern. Say instead that the README's existing list satisfies item 2 until help gains the list, and explicitly tell the auditor to assess items 3 and 4 independently. This preserves the intended transition from a README list to a live help list. An explicit qualification of only to the two documentation checks would refute the ambiguity; none appears in the rule.

claim 01M3YFCCEZ11A0FPG4EK330A6G of review 01M3YF2CB2260ZYAF6S0VNZ8GH

**low** — ARG8's fallback says only one check fails even when others may fail lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the complete ARG8 checklist and its `How to verify` bullets. Item 3 independently requires an environment variable for each dependency, and item 4 independently requires a startup check. The new fallback for a CLI whose `--help` does not list dependencies says `only item 1 fails`. For a CLI that also has no path override or startup check, that sentence literally marks just item 1 as failed and can hide failures of items 3 and 4 in the audit report. The writing standard asks for verifiable claims and conditions attached to the action they govern. Say instead that the README's existing list satisfies item 2 until help gains the list, and explicitly tell the auditor to assess items 3 and 4 independently. This preserves the intended transition from a README list to a live help list. An explicit qualification of `only` to the two documentation checks would refute the ambiguity; none appears in the rule. claim `01M3YFCCEZ11A0FPG4EK330A6G` of review `01M3YF2CB2260ZYAF6S0VNZ8GH`

👍 1

Fixed in fa0f0c9: the fallback now reads "Until then, the README keeps its list, which satisfies this item", so items 3 and 4 are judged on their own.

Fixed in fa0f0c9: the fallback now reads "Until then, the README keeps its list, which satisfies this item", so items 3 and 4 are judged on their own.

Same as the earlier findings on this reference: #96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land.

Same as the earlier findings on this reference: #96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land.

superseded by review 01M3YFZPZ8XQ0VH63F6QJX9JVX for head fa0f0c96f1f4f34bac356c22fe61e389b42e5d8c

superseded by review `01M3YFZPZ8XQ0VH63F6QJX9JVX` for head `fa0f0c96f1f4f34bac356c22fe61e389b42e5d8c`

🚀 1

jercik added 1 commit

2026-10-02 14:23:36 +00:00

fix(verify-unixy-cli): let arg8's readme fallback satisfy its own item only

commit-msg / commitlint (pull_request) Successful in 23s

Details

Node tests / node:test (pull_request) Successful in 1m33s

Details

Review / Review (pull_request_target) Successful in 9m24s

Details

fa0f0c96f1

Saying only item 1 fails could hide failures of the env-var and startup
checks, so the fallback now says the README list satisfies the README item.

forgejo-actions reviewed

2026-10-02 14:33:00 +00:00

skills/verify-doc-drift/SKILL.md

					
				@ -39,0 +40,4 @@

				Replace drifted text that restates a set the code defines with a pointer to the source that defines it; correcting the copy only restarts the clock on the next drift. Text restates a set when it lists every member, or states how many there are, of a set that a file, directory, schema, or command defines, such as the flags `--help` prints or the keys a config schema declares.

				Name a source the doc's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path.

medium — Repository source pointers need to match the documented release
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full verify-doc-drift skill and the related verify-readme guidance to use a CLI’s live --help. This new sentence permits any absolute repository URL as the replacement source for a published package’s exhaustive list. If a README shipped with release v1 links to a file on the repository’s moving default branch, that URL can show v2 keys or flags while the reader has v1 installed. The replacement then recreates factual drift while removing the v1 list. Require a URL pinned to the documented release for versioned documentation, or point to a version-matched command or file in the package; a living README can use a living source. This keeps the reader-reachable pointer and aligns it with the version being described. The writing standard says to scope version-dependent claims and prefer authoritative lookups. This is a static versioning risk in the instruction; I did not inspect a downstream published package or reproduce a mismatch.

claim 01M3YGAP3B4YSE0A22DAN9J9D5 of review 01M3YFZPZ8XQ0VH63F6QJX9JVX

**medium** — Repository source pointers need to match the documented release lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full verify-doc-drift skill and the related verify-readme guidance to use a CLI’s live --help. This new sentence permits any absolute repository URL as the replacement source for a published package’s exhaustive list. If a README shipped with release v1 links to a file on the repository’s moving default branch, that URL can show v2 keys or flags while the reader has v1 installed. The replacement then recreates factual drift while removing the v1 list. Require a URL pinned to the documented release for versioned documentation, or point to a version-matched command or file in the package; a living README can use a living source. This keeps the reader-reachable pointer and aligns it with the version being described. The writing standard says to scope version-dependent claims and prefer authoritative lookups. This is a static versioning risk in the instruction; I did not inspect a downstream published package or reproduce a mismatch. claim `01M3YGAP3B4YSE0A22DAN9J9D5` of review `01M3YFZPZ8XQ0VH63F6QJX9JVX`

🚀 1

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -5,2 +5,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code

**Pointed at from the README**: Once help lists them, the README names `--help` as the list of these external tools and adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list, which satisfies this item

low — ARG8 links to a nonexistent verify-readme section
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full ARG8 rule, the verify-readme SKILL.md, and ARG5, which delegates README quality to verify-readme. ARG8 tells the reader to follow verify-readme's "Sets defined elsewhere" for handling dependency lists, but verify-readme has no such section or wording; its Requirements section only says to disclose non-obvious prerequisites, including external binaries. An agent following the cross-reference cannot find the promised guidance and must guess how to reconcile a README pointer with that requirement. Adding the cited rule to verify-readme or changing ARG8 to point to existing, explicit guidance would resolve this. This is a direct comparison of the repository texts; no runtime behavior was tested.

claim 01M3YG5X3SG9WTKAXJKJ8NSNPK of review 01M3YFZPZ8XQ0VH63F6QJX9JVX

**low** — ARG8 links to a nonexistent verify-readme section lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full ARG8 rule, the verify-readme SKILL.md, and ARG5, which delegates README quality to verify-readme. ARG8 tells the reader to follow verify-readme's "Sets defined elsewhere" for handling dependency lists, but verify-readme has no such section or wording; its Requirements section only says to disclose non-obvious prerequisites, including external binaries. An agent following the cross-reference cannot find the promised guidance and must guess how to reconcile a README pointer with that requirement. Adding the cited rule to verify-readme or changing ARG8 to point to existing, explicit guidance would resolve this. This is a direct comparison of the repository texts; no runtime behavior was tested. claim `01M3YG5X3SG9WTKAXJKJ8NSNPK` of review `01M3YFZPZ8XQ0VH63F6QJX9JVX`

👎 1

Same as the earlier findings on this reference: #96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land.

Same as the earlier findings on this reference: #96 adds verify-readme's "## Sets defined elsewhere" section (origin/fix/verify-readme-point-to-sources), and this PR's body says to merge it after #96, so the reference resolves once both land.

Current main b93e79a contains verify-readme section "Sets defined elsewhere" at line 107 from merged #96 (92b9e1b). Composition d917b8b preserves it. The prior finding compared the pre-prerequisite branch tree; its missing-target claim does not hold for the current comparison.

Current main b93e79a contains verify-readme section "Sets defined elsewhere" at line 107 from merged #96 (92b9e1b). Composition d917b8b preserves it. The prior finding compared the pre-prerequisite branch tree; its missing-target claim does not hold for the current comparison.

superseded by review 01M4223W149AHGNXKK5R2RFZ96 for head d917b8bcc7927e8a1cefe023a0b6b828dcdbffc6

superseded by review `01M4223W149AHGNXKK5R2RFZ96` for head `d917b8bcc7927e8a1cefe023a0b6b828dcdbffc6`

🚀 1

jercik commented

2026-10-02 14:34:20 +00:00

Replying to review comment #104038

This is a real point, but I'm deferring it to a follow-up PR instead of pushing it here. This is review round 4, and from round 4 a wording refinement that changes neither behavior nor safety waits for a follow-up rather than restarting review on the whole diff.

Follow-up fix: in skills/verify-doc-drift/SKILL.md ("Restated sets"), change "an absolute repository URL" to "an absolute repository URL pinned to the release the doc describes, when the doc ships with a versioned package". Make the same change to the matching sentence in verify-readme's "Sets defined elsewhere" once #96 merges. No change in fa0f0c9.

> Replying to review comment #104038 This is a real point, but I'm deferring it to a follow-up PR instead of pushing it here. This is review round 4, and from round 4 a wording refinement that changes neither behavior nor safety waits for a follow-up rather than restarting review on the whole diff. Follow-up fix: in `skills/verify-doc-drift/SKILL.md` ("Restated sets"), change "an absolute repository URL" to "an absolute repository URL pinned to the release the doc describes, when the doc ships with a versioned package". Make the same change to the matching sentence in verify-readme's "Sets defined elsewhere" once #96 merges. No change in fa0f0c9.

jercik added 1 commit

2026-10-03 23:38:12 +00:00

fix(skills): compose source pointers with current CLI requirements

commit-msg / commitlint (pull_request) Successful in 25s

Details

Node tests / node:test (pull_request) Successful in 3m12s

Details

Review / Review (pull_request_target) Successful in 5m6s

Details

d917b8bcc7

jercik referenced this pull request

2026-10-03 23:39:07 +00:00

fix(skills): source pointers should match the documented release #109

jercik commented

2026-10-03 23:39:45 +00:00

Replying to review comment #104038

Tracked in #109, a bounded two-skill follow-up requiring release-matched commands/files or release-pinned repository/hosted-docs pointers. It stacks on #97 and does not claim #97 fixes this concession. The finding remains a static versioning risk; no downstream package mismatch was reproduced.

> Replying to review comment #104038 Tracked in https://code.j4k.dev/j4k-oss/agent-skills/pulls/109, a bounded two-skill follow-up requiring release-matched commands/files or release-pinned repository/hosted-docs pointers. It stacks on #97 and does not claim #97 fixes this concession. The finding remains a static versioning risk; no downstream package mismatch was reproduced.

forgejo-actions reviewed

2026-10-03 23:44:13 +00:00

skills/verify-doc-drift/SKILL.md Outdated

					
				@ -38,1 +38,4 @@

				## Restated sets: point instead of recopying

				Replace drifted text that restates a set the code defines with a pointer to the source that defines it; correcting the copy only restarts the clock on the next drift. Text restates a set when it lists every member, or states how many there are, of a set that a file, directory, schema, or command defines, such as the flags `--help` prints or the keys a config schema declares.

medium — New "Restated sets" rule has no exception for accepted ADRs or code-drift findings, contradicting the skill's "never edit an ADR just to match the code"

What I examined: the whole of skills/verify-doc-drift/SKILL.md after the change, focusing on the new "Restated sets: point instead of recopying" section, the existing "Fix direction and missing features" section just above it, and Task step 5.

What the skill says: "Fix direction" says an accepted or status-less ADR "is the source of truth for the decision it records: code contradicting it is code-drift", and it ends with "never edit an ADR just to match the code". It also says to "Change code only for a confirmed code-drift where the doc is the intended source of truth." The new section, which comes right after, says without condition to "Replace drifted text that restates a set the code defines with a pointer to the source that defines it". Its exceptions cover only a table of contents, a dated changelog or release note, "a contract the doc's reader can't see anywhere else", and "a number that is the subject of an argument". Neither ADRs nor code-drift findings are listed. Task step 5 now also tells the agent to "point a drifted restated set at its source".

What goes wrong: take an accepted ADR that records "We support three storage backends: S3, GCS, and Azure", in a repo where the code has since gained a fourth backend. The ADR rule makes this code-drift: the code changes and the ADR stays as written. The new section reads the ADR as text restating a set the code defines and tells the agent to replace the list with a pointer to the code. That rewrites the recorded decision so it matches whatever the code does now. The decision is lost, and the drift the audit should report disappears. The same happens to any non-ADR doc that is the source of truth for a set, such as a standard that lists required headers. The phrase "drifted text" doesn't help here, because the skill already uses "code-drift" for the opposite fix direction. An agent following the later and more specific section will edit docs that the skill says must not be edited.

This comes from reading the instructions; I did not run an agent against them. To refute it, the skill would need text that limits "Restated sets" to incorrect findings, or that exempts ADRs and docs that are the source of truth. I found none. A safe fix is to open the section with "For an incorrect finding," and add accepted ADRs and code-drift sources to the "Correct the copy in place instead" exceptions, or to say that the ADR rule takes precedence.

lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain
claim 01M4226JDH01M3XZ7A7ZCBC0M4 of review 01M4223W149AHGNXKK5R2RFZ96

**medium** — New "Restated sets" rule has no exception for accepted ADRs or code-drift findings, contradicting the skill's "never edit an ADR just to match the code" > What I examined: the whole of skills/verify-doc-drift/SKILL.md after the change, focusing on the new "Restated sets: point instead of recopying" section, the existing "Fix direction and missing features" section just above it, and Task step 5. > > What the skill says: "Fix direction" says an accepted or status-less ADR "is the source of truth for the decision it records: code contradicting it is `code-drift`", and it ends with "never edit an ADR just to match the code". It also says to "Change code only for a confirmed **code-drift** where the doc is the intended source of truth." The new section, which comes right after, says without condition to "Replace drifted text that restates a set the code defines with a pointer to the source that defines it". Its exceptions cover only a table of contents, a dated changelog or release note, "a contract the doc's reader can't see anywhere else", and "a number that is the subject of an argument". Neither ADRs nor code-drift findings are listed. Task step 5 now also tells the agent to "point a drifted restated set at its source". > > What goes wrong: take an accepted ADR that records "We support three storage backends: S3, GCS, and Azure", in a repo where the code has since gained a fourth backend. The ADR rule makes this code-drift: the code changes and the ADR stays as written. The new section reads the ADR as text restating a set the code defines and tells the agent to replace the list with a pointer to the code. That rewrites the recorded decision so it matches whatever the code does now. The decision is lost, and the drift the audit should report disappears. The same happens to any non-ADR doc that is the source of truth for a set, such as a standard that lists required headers. The phrase "drifted text" doesn't help here, because the skill already uses "code-drift" for the opposite fix direction. An agent following the later and more specific section will edit docs that the skill says must not be edited. > > This comes from reading the instructions; I did not run an agent against them. To refute it, the skill would need text that limits "Restated sets" to `incorrect` findings, or that exempts ADRs and docs that are the source of truth. I found none. A safe fix is to open the section with "For an `incorrect` finding," and add accepted ADRs and code-drift sources to the "Correct the copy in place instead" exceptions, or to say that the ADR rule takes precedence. lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M4226JDH01M3XZ7A7ZCBC0M4` of review `01M4223W149AHGNXKK5R2RFZ96`

👍 1

Fixed in 93db8b1: source-pointer replacement applies only to incorrect findings, including the task application step. Accepted/status-less ADR decisions and other code-drift sources retain their existing authority and user decision gate.

Fixed in 93db8b1: source-pointer replacement applies only to incorrect findings, including the task application step. Accepted/status-less ADR decisions and other code-drift sources retain their existing authority and user decision gate.

jercik marked this conversation as resolved

skills/verify-doc-drift/SKILL.md

					
				@ -39,0 +47,4 @@

				Correct the copy in place instead where no pointer can replace it:

				- a table of contents whose entries each say what an item covers, so the reader can choose which item to open before opening any of them

				- a dated record, such as a changelog entry or release note, that misstates the release it describes; a difference from the current code alone is not drift

low — The rule that a dated record differing from current code is not drift sits only in the restated-sets exceptions, so auditors still flag non-set changelog claims

Examined: the whole of skills/verify-doc-drift/SKILL.md, especially "What counts as a checkable claim", "Finding categories", and the new "Restated sets: point instead of recopying" section.

What the text says: the clause "a difference from the current code alone is not drift" is the second half of one bullet under "Correct the copy in place instead where no pointer can replace it", so it is framed as an exception that applies only to restated sets. Nowhere else does the skill exempt dated records. "What counts as a checkable claim" covers "Anything the reader could act on that the code fixes the answer to", and the audit loop has the agent read every doc in a unit and check each claim against the code.

What goes wrong: an agent auditing a CHANGELOG entry such as "1.4.0: default port is now 8080" or "added --foo", where current code uses 9090 or --bar, finds no rule that exempts it. The only rule that does is scoped to set copies, so the agent reports the entry as incorrect and "fixes" history. This breaks the writing skill's guidance to keep a rule, its definition, and its caveat together, and to generalize a rule to the broadest form that stays true.

Correction: move the general rule to the place where claims are defined. For example, add to "What counts as a checkable claim": "A dated record, such as a changelog entry or release note, is checked against the release it describes; a difference from the current code alone is not drift." Then shorten the bullet to "a dated record, such as a changelog entry or release note". This keeps the meaning and applies it to every claim in a dated record, not only to listed sets.

Proof gap: this comes from reading the text. I did not run an agent on a changelog to watch it mis-flag an entry.

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

**low** — The rule that a dated record differing from current code is not drift sits only in the restated-sets exceptions, so auditors still flag non-set changelog claims > Examined: the whole of skills/verify-doc-drift/SKILL.md, especially "What counts as a checkable claim", "Finding categories", and the new "Restated sets: point instead of recopying" section. > > What the text says: the clause "a difference from the current code alone is not drift" is the second half of one bullet under "Correct the copy in place instead where no pointer can replace it", so it is framed as an exception that applies only to restated sets. Nowhere else does the skill exempt dated records. "What counts as a checkable claim" covers "Anything the reader could act on that the code fixes the answer to", and the audit loop has the agent read every doc in a unit and check each claim against the code. > > What goes wrong: an agent auditing a CHANGELOG entry such as "1.4.0: default port is now 8080" or "added --foo", where current code uses 9090 or --bar, finds no rule that exempts it. The only rule that does is scoped to set copies, so the agent reports the entry as `incorrect` and "fixes" history. This breaks the writing skill's guidance to keep a rule, its definition, and its caveat together, and to generalize a rule to the broadest form that stays true. > > Correction: move the general rule to the place where claims are defined. For example, add to "What counts as a checkable claim": "A dated record, such as a changelog entry or release note, is checked against the release it describes; a difference from the current code alone is not drift." Then shorten the bullet to "a dated record, such as a changelog entry or release note". This keeps the meaning and applies it to every claim in a dated record, not only to listed sets. > > Proof gap: this comes from reading the text. I did not run an agent on a changelog to watch it mis-flag an entry. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M4226TB1AXK57E5PJ41RZVWH` of review `01M4223W149AHGNXKK5R2RFZ96`

🚀 1

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/io3-exit-codes.md

					
				@ -15,2 +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.

				**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.

low — IO3's "How to verify" leaves out the new requirement that the README point at --help for exit codes

Examined: skills/verify-unixy-cli/references/io3-exit-codes.md in full, the matching ARG8 reference (arg8-document-external-dependencies.md), and arg5-readme-quality.md.

What the text says: the diff adds this requirement to "Multi-state verdicts": "The README points at --help for the codes and keeps what help can't show, such as which codes are safe to retry." The updated "How to verify" paragraph checks only distinct codes, --help documentation, and rendering from the state-to-code table. It never mentions the README. The parallel change to ARG8 does add the README check to its verify bullet: "that the README points at --help rather than restating the list". arg5-readme-quality.md hands README rules to verify-readme and says nothing about exit codes.

What goes wrong: an agent auditing a CLI against IO3 uses "How to verify" as its checklist. If the README holds a full exit-code table that has drifted from the code, that agent passes the README. The one new README rule in IO3 then has no check.

Correction: end the verify sentence with ", and that the README points at --help for the codes instead of listing them". This matches the ARG8 bullet and adds no new requirement.

Proof gap: this comes from reading the text. I did not run an audit.

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

**low** — IO3's "How to verify" leaves out the new requirement that the README point at `--help` for exit codes > Examined: skills/verify-unixy-cli/references/io3-exit-codes.md in full, the matching ARG8 reference (arg8-document-external-dependencies.md), and arg5-readme-quality.md. > > What the text says: the diff adds this requirement to "Multi-state verdicts": "The README points at `--help` for the codes and keeps what help can't show, such as which codes are safe to retry." The updated "How to verify" paragraph checks only distinct codes, `--help` documentation, and rendering from the state-to-code table. It never mentions the README. The parallel change to ARG8 does add the README check to its verify bullet: "that the README points at `--help` rather than restating the list". arg5-readme-quality.md hands README rules to verify-readme and says nothing about exit codes. > > What goes wrong: an agent auditing a CLI against IO3 uses "How to verify" as its checklist. If the README holds a full exit-code table that has drifted from the code, that agent passes the README. The one new README rule in IO3 then has no check. > > Correction: end the verify sentence with ", and that the README points at `--help` for the codes instead of listing them". This matches the ARG8 bullet and adds no new requirement. > > Proof gap: this comes from reading the text. I did not run an audit. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M422731MXCGWSE50GDDM1QPW` of review `01M4223W149AHGNXKK5R2RFZ96`

👎 1

Candidate #111 is withdrawn without merge: verify-unixy-cli line22 requires reading each full reference, and lines79–81 require verifying each rule with evidence. IO3 already requires the README pointer and retry guidance in its body, so the assertion that How to verify alone is the audit checklist does not hold. The candidate repeated that existing rule and added no distinct verification operation (review111932). No missed audit was reproduced.

Candidate #111 is withdrawn without merge: verify-unixy-cli line22 requires reading each full reference, and lines79–81 require verifying each rule with evidence. IO3 already requires the README pointer and retry guidance in its body, so the assertion that How to verify alone is the audit checklist does not hold. The candidate repeated that existing rule and added no distinct verification operation (review111932). No missed audit was reproduced.

superseded by review 01M42HX6QX34CGE58C3SGMT98A for head e28d807d3be83b91a375c6d6aca88d689aa4d3d5

superseded by review `01M42HX6QX34CGE58C3SGMT98A` for head `e28d807d3be83b91a375c6d6aca88d689aa4d3d5`

🚀 1

jercik added 1 commit

2026-10-03 23:46:10 +00:00

fix(skills): source pointer fixes should retain ADR authority

commit-msg / commitlint (pull_request) Successful in 19s

Details

Node tests / node:test (pull_request) Successful in 3m9s

Details

Review / Review (pull_request_target) Successful in 6m22s

Details

93db8b1bee

jercik referenced this pull request

2026-10-03 23:47:48 +00:00

fix(skills): dated records should use their release evidence #110

jercik referenced this pull request

2026-10-03 23:48:04 +00:00

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

jercik commented

2026-10-03 23:49:03 +00:00

Replying to review comment #111906

Tracked in #110. It relocates the existing release-comparison caveat to claim classification and removes its repetition in the set exception. This clarifies the existing dated-record scope; no agent misclassification was reproduced, and #97 does not claim this follow-up is fixed before it merges.

> Replying to review comment #111906 Tracked in https://code.j4k.dev/j4k-oss/agent-skills/pulls/110. It relocates the existing release-comparison caveat to claim classification and removes its repetition in the set exception. This clarifies the existing dated-record scope; no agent misclassification was reproduced, and #97 does not claim this follow-up is fixed before it merges.

jercik commented

2026-10-03 23:49:07 +00:00

Replying to review comment #111907

Tracked in #111. It mirrors IO3's existing README pointer and retry-guidance requirement in its verification checklist; no new requirement is added. The checklist omission is verified in source, but no audit missed the requirement in an agent reproduction. This remains separate from #97.

> Replying to review comment #111907 Tracked in https://code.j4k.dev/j4k-oss/agent-skills/pulls/111. It mirrors IO3's existing README pointer and retry-guidance requirement in its verification checklist; no new requirement is added. The checklist omission is verified in source, but no audit missed the requirement in an agent reproduction. This remains separate from #97.

forgejo-actions reviewed

2026-10-03 23:52:31 +00:00

skills/verify-doc-drift/SKILL.md

					
				@ -38,1 +38,4 @@

				## Restated sets: point instead of recopying

				For an **incorrect** finding, replace drifted text that restates a set the code defines with a pointer to the source that defines it; correcting the copy only restarts the clock on the next drift. Text restates a set when it lists every member, or states how many there are, of a set that a file, directory, schema, or command defines, such as the flags `--help` prints or the keys a config schema declares.

medium — Restated-set rule misses accurate copies and incomplete lists

I read the added Restated sets section with this skill's Finding categories and Fix direction, and the repository's verify-readme/SKILL.md section 'Sets defined elsewhere'. The new gate applies only after a finding is already incorrect, and defines a restatement as a count or a list of every member. A currently accurate copy of the members has no category here: 'duplicate' covers another doc, not a code-defined set. A list presented as complete but already missing a member is also outside this definition, so an auditor can repair it by writing a new full list. Both leave a second copy that silently drifts when the source changes. The writing standard says to use a cheap authoritative lookup instead of copying the fact, and verify-readme explicitly treats a set copied from its source as a defect. Make this rule cover purported enumerations and counts whether accurate or incomplete, classify an accurate copy as duplicate, and point an incorrect partial list to its defining source. Retain the existing exceptions and the useful member-specific detail. This is a static reading of the instruction paths; there is no served-agent run to confirm actual behavior.

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

**medium** — Restated-set rule misses accurate copies and incomplete lists > I read the added Restated sets section with this skill's Finding categories and Fix direction, and the repository's verify-readme/SKILL.md section 'Sets defined elsewhere'. The new gate applies only after a finding is already **incorrect**, and defines a restatement as a count or a list of every member. A currently accurate copy of the members has no category here: 'duplicate' covers another doc, not a code-defined set. A list presented as complete but already missing a member is also outside this definition, so an auditor can repair it by writing a new full list. Both leave a second copy that silently drifts when the source changes. The writing standard says to use a cheap authoritative lookup instead of copying the fact, and verify-readme explicitly treats a set copied from its source as a defect. Make this rule cover purported enumerations and counts whether accurate or incomplete, classify an accurate copy as duplicate, and point an incorrect partial list to its defining source. Retain the existing exceptions and the useful member-specific detail. This is a static reading of the instruction paths; there is no served-agent run to confirm actual behavior. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M422QPDVR6SS4NFGW38BXF6Q` of review `01M422JERS4ADE390RJ27J88DD`

👎 1

This PR repairs drifted doc copies; it does not introduce accurate-code-copy inventory auditing. The existing audit loop explicitly says returning zero findings for accurate docs is the correct outcome. Classifying accurate source copies as duplicate and expanding enumeration coverage would change that policy, which the user excludes from this composition. The existing incorrect-finding gate also preserves accepted/status-less ADR and other code-drift authority. No served-agent behavior was reproduced, and no policy expansion is adopted.

This PR repairs drifted doc copies; it does not introduce accurate-code-copy inventory auditing. The existing audit loop explicitly says returning zero findings for accurate docs is the correct outcome. Classifying accurate source copies as duplicate and expanding enumeration coverage would change that policy, which the user excludes from this composition. The existing incorrect-finding gate also preserves accepted/status-less ADR and other code-drift authority. No served-agent behavior was reproduced, and no policy expansion is adopted.

superseded by review 01M42HX6QX34CGE58C3SGMT98A for head e28d807d3be83b91a375c6d6aca88d689aa4d3d5

superseded by review `01M42HX6QX34CGE58C3SGMT98A` for head `e28d807d3be83b91a375c6d6aca88d689aa4d3d5`

🚀 1

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md

					
				@ -4,3 +4,2 @@

**Mentioned in help output**: Either in the description or a dedicated section

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill)

**Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code

medium — ARG8 example bypasses the shared dependency list it requires

I read ARG8 in full, including its TypeScript example, and ARG9's requirement-model instructions. This new rule says help must be rendered from the list read by the startup check. Yet ARG8's immediately following example builds an independent ghPath from MYCLI_GH_PATH and the literal gh, calls execFileSync(ghPath, ["--version"]), and hard-codes the same dependency in its error text. It never reads ARG9's requirement model, which already has binary, pathEnvVar, install guidance, and a status check. An agent copying the only implementation example will create two dependency definitions and can satisfy the prose superficially while help and the fatal check drift apart when a dependency changes. Update the example so the fatal check consumes the same requirement records that render help, or replace it with a focused env-override illustration explicitly tied to that model. This preserves the useful startup-order and actionable-error guidance. The conflict is visible statically; I did not run a CLI implementation.

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

**medium** — ARG8 example bypasses the shared dependency list it requires > I read ARG8 in full, including its TypeScript example, and ARG9's requirement-model instructions. This new rule says help must be rendered from the list read by the startup check. Yet ARG8's immediately following example builds an independent `ghPath` from `MYCLI_GH_PATH` and the literal `gh`, calls `execFileSync(ghPath, ["--version"])`, and hard-codes the same dependency in its error text. It never reads ARG9's requirement model, which already has `binary`, `pathEnvVar`, install guidance, and a status check. An agent copying the only implementation example will create two dependency definitions and can satisfy the prose superficially while help and the fatal check drift apart when a dependency changes. Update the example so the fatal check consumes the same requirement records that render help, or replace it with a focused env-override illustration explicitly tied to that model. This preserves the useful startup-order and actionable-error guidance. The conflict is visible statically; I did not run a CLI implementation. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M422S6FWQDHDPKQM9JDQG00W` of review `01M422JERS4ADE390RJ27J88DD`

👍 1

Fixed in e28d807d3b: ARG8 consumes ARG9 shared command requirement records; removed independent hardcoded gh example.

Fixed in e28d807d3be83b91a375c6d6aca88d689aa4d3d5: ARG8 consumes ARG9 shared command requirement records; removed independent hardcoded gh example.

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -5,2 +5,2 @@

**Mentioned in help output**: Either in the description or a dedicated section

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill)

**Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code

**Pointed at from the README**: Once help lists them, a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools and adds what help can't show, such as how to install each one and, for one that needs it, how to authenticate it, plus version floors where needed, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list, which satisfies this item

medium — ARG8 duplicates installation guidance already defined for help

I read ARG8, ARG9, and verify-readme's 'Sets defined elsewhere' guidance. ARG8 says the README should add what --help cannot show, then names how to install each dependency and authenticate it. ARG9 already requires each command requirement to carry install guidance and optional auth fix commands, and its Requires output shows inline remediation when a requirement is missing or unauthorized. The same per-tool instructions would therefore live in both help and the README; changing an install command or auth procedure could leave one stale even while the dependency list still points to help. Change this sentence and its verification bullet to point readers to --help for the list and the fixes it renders, and keep only genuinely additional setup or version constraints in the README. This retains discoverability for README readers without copying details whose source can express them. This is a static comparison of the instructions; I did not verify a particular CLI's output.

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

**medium** — ARG8 duplicates installation guidance already defined for help > I read ARG8, ARG9, and verify-readme's 'Sets defined elsewhere' guidance. ARG8 says the README should add what `--help` cannot show, then names how to install each dependency and authenticate it. ARG9 already requires each command requirement to carry install guidance and optional auth fix commands, and its `Requires` output shows inline remediation when a requirement is missing or unauthorized. The same per-tool instructions would therefore live in both help and the README; changing an install command or auth procedure could leave one stale even while the dependency list still points to help. Change this sentence and its verification bullet to point readers to `--help` for the list and the fixes it renders, and keep only genuinely additional setup or version constraints in the README. This retains discoverability for README readers without copying details whose source can express them. This is a static comparison of the instructions; I did not verify a particular CLI's output. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M422SV116ZCDGDM1G1T4W336` of review `01M422JERS4ADE390RJ27J88DD`

👍 1

Fixed in e28d807d3b: retain per-tool setup only for missing help detail; independent fatal check and README fallback remain.

Fixed in e28d807d3be83b91a375c6d6aca88d689aa4d3d5: retain per-tool setup only for missing help detail; independent fatal check and README fallback remain.

jercik marked this conversation as resolved

jercik referenced this pull request

2026-10-04 00:03:35 +00:00

fix(skills): source pointers should match the documented release #109

jercik added 1 commit

2026-10-04 04:14:09 +00:00

fix: align dependency documentation with command requirements

commit-msg / commitlint (pull_request) Successful in 28s

Details

Node tests / node:test (pull_request) Successful in 4m24s

Details

Review / Review (pull_request_target) Successful in 4m53s

Details

e28d807d3b

forgejo-actions reviewed

2026-10-04 04:19:01 +00:00

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md

					
				@ -5,2 +5,2 @@

**Mentioned in help output**: Either in the description or a dedicated section

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill)

**Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code

**Pointed at from the README**: Once help lists them, a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools and adds per-tool installation, authentication, or version guidance where help does not provide it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list, which satisfies this item

low — ARG8 item 2 restates verify-readme's "Sets defined elsewhere" rule while also pointing at it

What I examined: ARG8 item 2 (changed in this diff), verify-unixy-cli/SKILL.md frontmatter, and verify-readme/SKILL.md's "Sets defined elsewhere" section.

What the subject says: item 2 now spells out the README rule in full — name --help as the list, add per-tool installation/authentication/version guidance where help lacks it, "without a count or a claim to cover them all" — and then cites verify-readme's "Sets defined elsewhere". That verify-readme section already says the README names the source instead of listing members, adds "the detail the source can't show, for each member that needs it", and "don't introduce it with a count or a claim to cover them all". verify-unixy-cli declares the dependency (axskills.requires: "verify-readme"), and ARG5 calls verify-readme the canonical README contract.

Why it matters: the writing skill's "One Idea, One Place" says to call declared skill dependencies instead of duplicating their instructions. The 60-word item is the longest in the list. It also keeps a second copy of verify-readme's wording, which will drift when verify-readme changes. The copy has already narrowed the rule: verify-readme also covers what a member means and why it exists, but item 2 names only installation, authentication, and version guidance.

Proposed correction: "2. Pointed at from the README: Once help lists them, the README's "Requirements" or "Prerequisites" section points at --help as verify-readme's "Sets defined elsewhere" describes. Until then, a README list satisfies this item." This keeps the item's trigger (help lists them), the fallback (a README list satisfies the item), the section names, and the pointer. The per-tool detail and the no-count rule stay where verify-readme defines them.

What would refute it: if ARG8 is meant to be read without verify-readme loaded. The declared requires and ARG5's deferral show that verify-readme is loaded.

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

**low** — ARG8 item 2 restates verify-readme's "Sets defined elsewhere" rule while also pointing at it > What I examined: ARG8 item 2 (changed in this diff), verify-unixy-cli/SKILL.md frontmatter, and verify-readme/SKILL.md's "Sets defined elsewhere" section. > > What the subject says: item 2 now spells out the README rule in full — name `--help` as the list, add per-tool installation/authentication/version guidance where help lacks it, "without a count or a claim to cover them all" — and then cites verify-readme's "Sets defined elsewhere". That verify-readme section already says the README names the source instead of listing members, adds "the detail the source can't show, for each member that needs it", and "don't introduce it with a count or a claim to cover them all". verify-unixy-cli declares the dependency (`axskills.requires: "verify-readme"`), and ARG5 calls verify-readme the canonical README contract. > > Why it matters: the writing skill's "One Idea, One Place" says to call declared skill dependencies instead of duplicating their instructions. The 60-word item is the longest in the list. It also keeps a second copy of verify-readme's wording, which will drift when verify-readme changes. The copy has already narrowed the rule: verify-readme also covers what a member means and why it exists, but item 2 names only installation, authentication, and version guidance. > > Proposed correction: "2. **Pointed at from the README**: Once help lists them, the README's \"Requirements\" or \"Prerequisites\" section points at `--help` as verify-readme's \"Sets defined elsewhere\" describes. Until then, a README list satisfies this item." This keeps the item's trigger (help lists them), the fallback (a README list satisfies the item), the section names, and the pointer. The per-tool detail and the no-count rule stay where verify-readme defines them. > > What would refute it: if ARG8 is meant to be read without verify-readme loaded. The declared `requires` and ARG5's deferral show that verify-readme is loaded. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M42J0ZEAST8BJD0NDNQNBSJZ` of review `01M42HX6QX34CGE58C3SGMT98A`

🚀 1

jercik marked this conversation as resolved

jercik commented

2026-10-04 04:25:25 +00:00

Replying to review comment #112069

Claim 01M42J0ZEAST8BJD0NDNQNBSJZ: the overlapping README prose is visible, but the proposed deletion is scope-rejected under this task's explicit requirement to preserve per-tool installation/authentication/version detail and conditional README fallback from actual main. The canonical verify-readme reference remains and owns the general README contract. ARG8 states the external-tool obligation and its migration trigger. No new concision policy is adopted, and this is not claimed an empirical disproof of overlap.

Replying to review comment #101108

Current review 01M42HX6QX34CGE58C3SGMT98A, head e28d807d3be83b91a375c6d6aca88d689aa4d3d5, report-only high claim 01M42J13VKFSQ9K9RB1M26B0GV: the reader-reachable source list is the accepted bounded pointer contract. A repository URL already provides an actionable source; the report supplies no broken reader path caused by excluding a hosted-documentation target. Replacing this contract with another skill's rule or broadening its targets is outside minimal composition. Scope-rejected, not asserted empirically disproved. No matching inline anchor is exposed; no native per-claim transition is claimed.

Report-only low claim 01M42J1GMM2DYA6CYT6EX2J1VV: ARG9 explicitly defines each requirement's status/fix/auth fields and command dependencies' binary, pathEnvVar, and install guidance, and requires the runtime requirement model in its verification. ARG8's command records refer to these existing per-command requirements; using them in both render and startup paths implements the task's shared-source repair. ARG8 item 3 independently requires the path override. No new model or public API is introduced. This is evidence-backed disagreement with a claimed undefined/new contract; no inline anchor exists for a native transition.

Both report-only entries remain unadjudicated in the service's current report. Local source dispositions do not clear that review gate. No vote, rerun, dispatch, summary acknowledgment, or READY claim is made. Rejected bucket claims about optional path overrides and Task 5 sweep are retained as rejected report evidence, not adopted changes.

> Replying to review comment #112069 Claim `01M42J0ZEAST8BJD0NDNQNBSJZ`: the overlapping README prose is visible, but the proposed deletion is scope-rejected under this task's explicit requirement to preserve per-tool installation/authentication/version detail and conditional README fallback from actual main. The canonical verify-readme reference remains and owns the general README contract. ARG8 states the external-tool obligation and its migration trigger. No new concision policy is adopted, and this is not claimed an empirical disproof of overlap. > Replying to review comment #101108 Current review `01M42HX6QX34CGE58C3SGMT98A`, head `e28d807d3be83b91a375c6d6aca88d689aa4d3d5`, report-only high claim `01M42J13VKFSQ9K9RB1M26B0GV`: the reader-reachable source list is the accepted bounded pointer contract. A repository URL already provides an actionable source; the report supplies no broken reader path caused by excluding a hosted-documentation target. Replacing this contract with another skill's rule or broadening its targets is outside minimal composition. Scope-rejected, not asserted empirically disproved. No matching inline anchor is exposed; no native per-claim transition is claimed. Report-only low claim `01M42J1GMM2DYA6CYT6EX2J1VV`: ARG9 explicitly defines each requirement's status/fix/auth fields and command dependencies' `binary`, `pathEnvVar`, and install guidance, and requires the runtime requirement model in its verification. ARG8's command records refer to these existing per-command requirements; using them in both render and startup paths implements the task's shared-source repair. ARG8 item 3 independently requires the path override. No new model or public API is introduced. This is evidence-backed disagreement with a claimed undefined/new contract; no inline anchor exists for a native transition. Both report-only entries remain unadjudicated in the service's current report. Local source dispositions do not clear that review gate. No vote, rerun, dispatch, summary acknowledgment, or READY claim is made. Rejected bucket claims about optional path overrides and Task 5 sweep are retained as rejected report evidence, not adopted changes.

jercik commented

2026-10-04 04:30:18 +00:00

Replying to the review 01M42HX6QX34CGE58C3SGMT98A report ("Other claims", unadjudicated) on head e28d807d3b

This is round 7 or later, so the fix gate allows only security, data-corruption, or data-loss fixes. Neither unadjudicated claim is in that class, and no thread exists for either, so both end acknowledged. I read both against the files.

01M42J13VKFSQ9K9RB1M26B0GV (high): real, but a wording gap rather than a high-impact defect. skills/verify-doc-drift/SKILL.md ("Restated sets") lists reachable pointer targets as "a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path". skills/verify-readme/SKILL.md ("Sets defined elsewhere") says "an absolute repository or hosted docs URL". Deferred follow-up: in skills/verify-doc-drift/SKILL.md, change "an absolute repository URL" to "an absolute repository or hosted docs URL".
01M42J1GMM2DYA6CYT6EX2J1VV (low): real, small. skills/verify-unixy-cli/references/arg8-document-external-dependencies.md says "command records in ARG9's requirement model", while ARG9 defines "command dependencies" (binary, optional pathEnvVar, install guidance). Deferred follow-up in the ARG8 file: replace "command records" with "command dependencies".

Neither re-raises the earlier restated-sets or IO3 findings, which stay as recorded on their threads.

> Replying to the review `01M42HX6QX34CGE58C3SGMT98A` report ("Other claims", unadjudicated) on head e28d807d3be83b91a375c6d6aca88d689aa4d3d5 This is round 7 or later, so the fix gate allows only security, data-corruption, or data-loss fixes. Neither unadjudicated claim is in that class, and no thread exists for either, so both end acknowledged. I read both against the files. - `01M42J13VKFSQ9K9RB1M26B0GV` (high): real, but a wording gap rather than a high-impact defect. `skills/verify-doc-drift/SKILL.md` ("Restated sets") lists reachable pointer targets as "a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path". `skills/verify-readme/SKILL.md` ("Sets defined elsewhere") says "an absolute repository or hosted docs URL". Deferred follow-up: in `skills/verify-doc-drift/SKILL.md`, change "an absolute repository URL" to "an absolute repository or hosted docs URL". - `01M42J1GMM2DYA6CYT6EX2J1VV` (low): real, small. `skills/verify-unixy-cli/references/arg8-document-external-dependencies.md` says "command records in ARG9's requirement model", while ARG9 defines "command dependencies" (`binary`, optional `pathEnvVar`, install guidance). Deferred follow-up in the ARG8 file: replace "command records" with "command dependencies". Neither re-raises the earlier restated-sets or IO3 findings, which stay as recorded on their threads.

jercik merged commit 2f0b6a4385 into main

2026-10-04 04:55:35 +00:00

jercik referenced this pull request from a commit

2026-10-04 04:55:36 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets (#97)

jercik referenced this pull request

2026-10-06 07:45:00 +00:00

fix(skills): source pointers should match the documented release #109

jercik referenced this pull request

2026-10-06 07:45:20 +00:00

fix(skills): dated records should use their release evidence #110

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!97

 @ -4,3 +4,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Pointed at from the README**: Once help lists them (item 2), a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools, then adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and item 2 is reported as failing

 @ -4,3 +4,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Pointed at from the README**: Once help lists them (item 2), a "Requirements" or "Prerequisites" section names `--help` as the list of these external tools, then adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and item 2 is reported as failing

 @ -5,2 +5,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code
 . **Pointed at from the README**: Once help lists them, the README names `--help` as the list of these external tools and adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and only item 1 fails

 @ -5,2 +5,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code
 . **Pointed at from the README**: Once help lists them, the README names `--help` as the list of these external tools and adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list and only item 1 fails

 @ -5,2 +5,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Listed in help output**: Rendered from the same list the startup check reads, such as ARG9's requirement model, so help can't drift from the code
 . **Pointed at from the README**: Once help lists them, the README names `--help` as the list of these external tools and adds what help can't show, such as install steps, version floors, or auth setup, for the tools that need it, without a count or a claim to cover them all (see verify-readme's "Sets defined elsewhere"). Until then, the README keeps its list, which satisfies this item

Rows
Columns