docs: fix stale .sh references and version badge in all 7 READMEs#7
Merged
Conversation
Two leftover artifacts that the v1.1.0 rewrite PR missed because the translation subagents were scoped to Requirements / Install / Platform / Plugin Layout / Testing / Inspired By — they did not touch other sections. 1. "How It Works" section (line ~87 in every README) still mentioned `hooks/stop-hook.sh`. That file was deleted in the v1.1.0 rewrite — the current hook is `hooks/stop-hook.js`. 2. The "version" shield badge (line 7) has been hardcoded to `version-1.0.0-green.svg` since the initial release. Every subsequent release (v1.0.1, v1.0.2, v1.0.3, v1.1.0) left it stale. Bump to 1.1.0 and leave a TODO for next time. Fixed across all 7 READMEs (English + zh/ja/ko/es/vi/pt) with a single sed pass — the edit is identical in every file. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
JonyanDunh
added a commit
that referenced
this pull request
Apr 12, 2026
Eight gap-coverage tests added after a post-release self-audit of v1.3.0. Every scenario passes on the first run against the existing v1.3.0 hook code — these tests do NOT fix any bug, they lock in already-correct behavior so a future refactor cannot accidentally regress it. ## Gaps closed 1. **Hot-reload + NO_FILE_CHANGES in the same iteration** (test/stop-hook-haiku.test.js) The hot-reload step (#2 in the hook) must reset effectiveStreak to 0 BEFORE the Haiku verdict (#7) is processed in the same iteration. Otherwise a state with streak=2/3 + a redefined prompt + a clean verdict would exit on the new task's very first turn (3/3) instead of starting fresh (1/3). The new test sets exit_confirmations=3, no_change_streak=2, edits the prompt file mid-test, fires the hook with WATCHDOG_FAKE_HAIKU_VERDICT=NO_FILE_CHANGES, and asserts the loop continues with `1/3` (NOT `3/3`), persists the new prompt, and sets no_change_streak=1. 2. **Hot-reload + --no-classifier together** (test/stop-hook.test.js) Two orthogonal features composed in one iteration. The test strips `claude` from PATH and uses process.execPath to spawn the hook, confirming that no Haiku subprocess is ever attempted. Verifies the hot-reloaded prompt is re-fed AND no askHaiku() failure messages appear in stderr. 3. **Standalone --watch-prompt-file with no prompt at all** (test/setup.test.js) The setup-watchdog parser must catch the missing --prompt-file companion before falling through to the generic "No prompt provided" error. Asserts the user gets the *useful* error message (-watch- prompt-file requires --prompt-file) and NOT the generic fallback. 4. **Hand-corrupted exit_confirmations field** (test/stop-hook-haiku.test.js) Five sub-cases verifying the defensive default in stop-hook.js (`typeof === 'number' && >= 1 ? value : 1`) catches every weird shape a hand-edited state file might contain: - string "3" -> defaults to 1 (typeof !== 'number') - 0 -> defaults to 1 (< 1) - -5 -> defaults to 1 (< 1) - null -> defaults to 1 (typeof !== 'number') - 3.5 -> honored as-is (typeof === 'number' && >= 1), streak math is integer so the threshold first fires at newStreak == 4, not 3 — documented quirky behavior, locked in to prevent silent regression if a refactor "rounds" the float ## Test count Pre-PR: 124 active + 2 skipped (126 total). Post-PR: 132 active + 2 skipped (134 total). Net new: 8 tests. ## Result All 8 new tests passed on the first run against unmodified v1.3.0 code. The only failure during development was a too-broad regex in my own assertion (the `--no-classifier` info log itself contains the word "classifier", so a literal `doesNotMatch(/classifier/i)` was wrong) — the assertion was tightened to the specific askHaiku() failure phrases ("CLI not found", "judgment call failed", "ambiguous"). No production code was changed in this PR. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
JonyanDunh
added a commit
that referenced
this pull request
Apr 12, 2026
…es (#15) Eight gap-coverage tests added after a post-release self-audit of v1.3.0. Every scenario passes on the first run against the existing v1.3.0 hook code — these tests do NOT fix any bug, they lock in already-correct behavior so a future refactor cannot accidentally regress it. ## Gaps closed 1. **Hot-reload + NO_FILE_CHANGES in the same iteration** (test/stop-hook-haiku.test.js) The hot-reload step (#2 in the hook) must reset effectiveStreak to 0 BEFORE the Haiku verdict (#7) is processed in the same iteration. Otherwise a state with streak=2/3 + a redefined prompt + a clean verdict would exit on the new task's very first turn (3/3) instead of starting fresh (1/3). The new test sets exit_confirmations=3, no_change_streak=2, edits the prompt file mid-test, fires the hook with WATCHDOG_FAKE_HAIKU_VERDICT=NO_FILE_CHANGES, and asserts the loop continues with `1/3` (NOT `3/3`), persists the new prompt, and sets no_change_streak=1. 2. **Hot-reload + --no-classifier together** (test/stop-hook.test.js) Two orthogonal features composed in one iteration. The test strips `claude` from PATH and uses process.execPath to spawn the hook, confirming that no Haiku subprocess is ever attempted. Verifies the hot-reloaded prompt is re-fed AND no askHaiku() failure messages appear in stderr. 3. **Standalone --watch-prompt-file with no prompt at all** (test/setup.test.js) The setup-watchdog parser must catch the missing --prompt-file companion before falling through to the generic "No prompt provided" error. Asserts the user gets the *useful* error message (-watch- prompt-file requires --prompt-file) and NOT the generic fallback. 4. **Hand-corrupted exit_confirmations field** (test/stop-hook-haiku.test.js) Five sub-cases verifying the defensive default in stop-hook.js (`typeof === 'number' && >= 1 ? value : 1`) catches every weird shape a hand-edited state file might contain: - string "3" -> defaults to 1 (typeof !== 'number') - 0 -> defaults to 1 (< 1) - -5 -> defaults to 1 (< 1) - null -> defaults to 1 (typeof !== 'number') - 3.5 -> honored as-is (typeof === 'number' && >= 1), streak math is integer so the threshold first fires at newStreak == 4, not 3 — documented quirky behavior, locked in to prevent silent regression if a refactor "rounds" the float ## Test count Pre-PR: 124 active + 2 skipped (126 total). Post-PR: 132 active + 2 skipped (134 total). Net new: 8 tests. ## Result All 8 new tests passed on the first run against unmodified v1.3.0 code. The only failure during development was a too-broad regex in my own assertion (the `--no-classifier` info log itself contains the word "classifier", so a literal `doesNotMatch(/classifier/i)` was wrong) — the assertion was tightened to the specific askHaiku() failure phrases ("CLI not found", "judgment call failed", "ambiguous"). No production code was changed in this PR. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
JonyanDunh
added a commit
that referenced
this pull request
Apr 12, 2026
…ited
Make the existing "default = unlimited" behavior explicit in every user-
facing surface, and stop showing `--max-iterations 0` as the way to
express "no cap". The natural way is now to just omit the flag.
## Why
The current behavior (verified in `scripts/setup-watchdog.js:22` and
`hooks/stop-hook.js:154`) is already that not passing `--max-iterations`
means an unlimited loop — `maxIterations` defaults to `0` in the parser,
and the hook's hard-stop check is `if (state.max_iterations > 0 && ...)`,
so a value of `0` never triggers the cap.
But the docs were misleading users into thinking `--max-iterations 0` was
something they had to write to opt into "unlimited", when actually
omitting the flag is exactly equivalent. Worse, the `--no-classifier`
section's example showed `--no-classifier --max-iterations 0` as the
canonical "unbounded ralph-loop-style run" syntax, which made the `0`
look mandatory for that use case.
## What changed
No production code or behavior changes. Pure documentation cleanup:
- **`commands/help.md`** (the in-Claude-Code reference users see via
`/watchdog:help`):
- The `--no-classifier` example dropped from `--no-classifier
--max-iterations 0` to plain `--no-classifier`
- The `--max-iterations` option description now leads with "**optional
safety cap**" and explicitly states "If you don't pass it, the loop
is unlimited"
- The `--no-classifier` option description's "Pair with
`--max-iterations 0`" advice changed to "**Just omit
`--max-iterations`**"
- The "Best Practices" item renamed from "Always set `--max-iterations`"
to "Set `--max-iterations` for most tasks", with an explicit note that
omitting the flag is the correct way to express "unlimited"
- **`scripts/setup-watchdog.js` (`printHelp()`)**: the no-classifier
quick-usage example dropped its `--max-iterations 20` and gained an
inline comment `# no --max-iterations = unlimited`. A new three-line
trailer at the bottom of the help output explicitly explains that
`--max-iterations` is optional and `--max-iterations 0` is no longer
needed.
- **All 7 READMEs** (`README.{md,zh,es,ja,ko,vi,pt}.md`):
- The `--no-classifier` subsection's example dropped `--max-iterations 0`
- The surrounding paragraph reworded to lead with "**`--max-iterations`
is optional**" and explicitly tell the user they no longer need to
pass `--max-iterations 0`
- The "Best Practices" section #4 renamed from "Always set
`--max-iterations`" to "Set `--max-iterations` for most tasks", with
a new paragraph explicitly endorsing flag omission for unlimited
loops
## Backward compatibility
The CLI still accepts `--max-iterations 0` exactly as before — it is
parsed, stored as `max_iterations: 0` in the state file, and the hook
treats it as "no cap" because the `> 0` check fails. Existing watchdogs
that pass `0` keep working unchanged. This PR only changes the
*recommended* and *documented* way to express "unlimited"; the
*supported* ways now include both "omit the flag" and "pass 0", with
the former being the new natural form.
No state file schema changes. No new fields. No new flags. No version
bump (docs-only, following the convention of PRs #7 and #15).
## Test plan
- [x] 132-test suite still passes locally (132 active + 2 skipped, 0
failures) — no behavior change so no test additions needed
- [x] `node --test test/*.test.js` clean
- [x] Confirmed no remaining stale references via
`Grep --max-iterations 0` — every remaining match is in the new
explanatory text or the existing backward-compat test
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4 tasks
JonyanDunh
added a commit
that referenced
this pull request
Apr 12, 2026
…ited (#16) Make the existing "default = unlimited" behavior explicit in every user- facing surface, and stop showing `--max-iterations 0` as the way to express "no cap". The natural way is now to just omit the flag. ## Why The current behavior (verified in `scripts/setup-watchdog.js:22` and `hooks/stop-hook.js:154`) is already that not passing `--max-iterations` means an unlimited loop — `maxIterations` defaults to `0` in the parser, and the hook's hard-stop check is `if (state.max_iterations > 0 && ...)`, so a value of `0` never triggers the cap. But the docs were misleading users into thinking `--max-iterations 0` was something they had to write to opt into "unlimited", when actually omitting the flag is exactly equivalent. Worse, the `--no-classifier` section's example showed `--no-classifier --max-iterations 0` as the canonical "unbounded ralph-loop-style run" syntax, which made the `0` look mandatory for that use case. ## What changed No production code or behavior changes. Pure documentation cleanup: - **`commands/help.md`** (the in-Claude-Code reference users see via `/watchdog:help`): - The `--no-classifier` example dropped from `--no-classifier --max-iterations 0` to plain `--no-classifier` - The `--max-iterations` option description now leads with "**optional safety cap**" and explicitly states "If you don't pass it, the loop is unlimited" - The `--no-classifier` option description's "Pair with `--max-iterations 0`" advice changed to "**Just omit `--max-iterations`**" - The "Best Practices" item renamed from "Always set `--max-iterations`" to "Set `--max-iterations` for most tasks", with an explicit note that omitting the flag is the correct way to express "unlimited" - **`scripts/setup-watchdog.js` (`printHelp()`)**: the no-classifier quick-usage example dropped its `--max-iterations 20` and gained an inline comment `# no --max-iterations = unlimited`. A new three-line trailer at the bottom of the help output explicitly explains that `--max-iterations` is optional and `--max-iterations 0` is no longer needed. - **All 7 READMEs** (`README.{md,zh,es,ja,ko,vi,pt}.md`): - The `--no-classifier` subsection's example dropped `--max-iterations 0` - The surrounding paragraph reworded to lead with "**`--max-iterations` is optional**" and explicitly tell the user they no longer need to pass `--max-iterations 0` - The "Best Practices" section #4 renamed from "Always set `--max-iterations`" to "Set `--max-iterations` for most tasks", with a new paragraph explicitly endorsing flag omission for unlimited loops ## Backward compatibility The CLI still accepts `--max-iterations 0` exactly as before — it is parsed, stored as `max_iterations: 0` in the state file, and the hook treats it as "no cap" because the `> 0` check fails. Existing watchdogs that pass `0` keep working unchanged. This PR only changes the *recommended* and *documented* way to express "unlimited"; the *supported* ways now include both "omit the flag" and "pass 0", with the former being the new natural form. No state file schema changes. No new fields. No new flags. No version bump (docs-only, following the convention of PRs #7 and #15). ## Test plan - [x] 132-test suite still passes locally (132 active + 2 skipped, 0 failures) — no behavior change so no test additions needed - [x] `node --test test/*.test.js` clean - [x] Confirmed no remaining stale references via `Grep --max-iterations 0` — every remaining match is in the new explanatory text or the existing backward-compat test Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two leftover stale refs that the v1.1.0 rewrite PR (#6) missed because the 6 translation subagents were scoped to specific sections (Requirements / Install / Platform / Plugin Layout / Testing / Inspired By) and never touched other parts of the READMEs.
Fixed across all 7 READMEs with a single `sed` pass — the edit is identical in every file. No translation needed (both changes are URLs / filenames).
Test plan
Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com