fix(claude-ops): series-agnostic changelog grep, raw-md channel, ultracode lane effort

[kyle-sexton]

No linked issue.

Doc-alignment roster row(s) 62, 77, 86. Version claim: claude-ops 0.27.0 -> 0.27.1.

STATUS: NOT READY TO MERGE — unverified. The producing agent (and in most cases its verifier) was terminated mid-run by a model usage limit on 2026-08-04. This PR exists so the work is durable on the remote rather than stranded in a local worktree. Before merge it needs a fresh-context verifier pass with the rationale withheld, per the campaign's producer-never-self-certifies rule.

Related

• Campaign save-point and remaining-work ledger: Doc-alignment roster-tail campaign — durable save-point (2026-08-04 clean-stop) #1941
• Merge runbook for the already-verified queue: .work/doc-alignment/MERGE-RUNBOOK-2026-08-04.md (memory-tier, machine-local)

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 4m 10s —— View job

---

Claude finished the code review

• Gather context (PR body, changed files, custom instructions)
• Fetch diff against origin/main
• Review each changed file for correctness / CLAUDE.md alignment
• Post final review

Summary

Reviewed the diff (git diff origin/main...HEAD). Most of this PR is solid — the ultracode effort addition is correctly wired end-to-end (validation list, docstring, config docs, and new test assertions in lane-launcher.test.sh), and I independently confirmed via the CLI reference page that --effort ultracode is real and requires CC ≥ 2.1.203. One finding below calls the PR's headline "Fixed" claim into question; the rest are smaller compliance/verification gaps.

Findings

1. The .md-channel fix doesn't appear to solve the truncation it claims to fix (needs re-verification before merge)

CHANGELOG.md#L23-L27, also SKILL.md#L31, SKILL.md#L168, read-actions.md#L11

The changelog entry claims the rendered HTML page (~2.7MB) gets silently truncated by WebFetch, "losing deep versions," and that switching every fetch reference to the .md sibling (~511KB) fixes this because it "serves the same content byte-stable." I fetched https://code.claude.com/docs/en/changelog.md directly (the exact URL this PR now points the skill at) and asked it to confirm whether older version headers (2.1.0, 2.0.0) are present. They are not — the tool reports the content it received is truncated, stopping around 2.1.183 even though the latest entry is 2.1.221. That's the same "losing deep versions" symptom the bug report describes, just on the new URL instead of the old one.

This suggests the root cause isn't rendered-HTML-vs-markdown format, but WebFetch's own size-based summarization (its docs note "results may be summarized if the content is very large") — and 511KB may still be well past that threshold. If so, this fix doesn't actually close the bug it's filed against; deep versions would still silently vanish from fetch/status/diff on this skill.

Per CLAUDE.md's fresh-docs mandate, this is exactly the kind of claim that needs to be confirmed against a live fetch this session rather than reasoned about — and a live fetch appears to contradict it. Given the PR is already flagged "unverified" pending a fresh-context verifier pass, I'd treat this as the one item that specifically needs re-testing (e.g., fetch a version range spanning older entries and confirm it actually resolves) before merge.

2. ultracode verification claim isn't citing a URL, unlike the sibling costs.md claim in the same PR

CHANGELOG.md#L28-L32, config.md#L38

Both say "verified 2026-08-04 against the CLI reference" but never link https://code.claude.com/docs/en/cli-reference (which is indexed in docs/OFFICIAL-DOCS.md). Contrast with the observability change in the same PR, which does cite <https://code.claude.com/docs/en/costs.md> inline. CLAUDE.md's fresh-docs mandate says to "cite the URL" for documented-harness-behavior changes — this is a minor, easy-to-fix inconsistency (I did independently confirm the underlying fact is correct: ultracode requires CC ≥ 2.1.203 per that page).

3. Unverified claim about older-CLI fallback behavior

config.md#L38

"an older CLI rejects the value and starts the session at default effort" describes behavior of a pre-2.1.203 CLI given an effort value it doesn't recognize. The current CLI reference page only documents current behavior, not this historical fallback — so this specific clause looks like an assumption rather than something confirmed from a fetched page this session. If it's wrong (e.g., an old CLI actually errors out and never starts the session, rather than silently falling back to default effort), an operator reading this doc would be misled about the actual failure mode. Low severity since it's just a doc caveat, not launcher logic, but worth a quick sanity check or softening to "may reject/ignore the value" if unconfirmed.

4. Tests not executed

I was unable to run lane-launcher.test.sh in this sandbox (execution required approval that wasn't available in this context) — I verified the new test assertions by reading the script and confirmed VALID_EFFORTS / the err-message path wire up correctly by inspection, but a fresh run of the actual suite is worth doing before merge.

Everything else checked out

• plugin.json version bump (0.27.0 → 0.27.1) matches the new CHANGELOG.md entry.
• The changelog status grep fix (v2\.1\. → -E --grep="CC v[0-9]+\.[0-9]+\.[0-9]+") is correctly generalized; confirmed no other file in skills/changelog/ still hardcodes the series pin (remaining v2.1.152-style strings are illustrative examples, as the changelog entry states).
• lane-launcher.sh's VALID_EFFORTS addition is correctly threaded through to the existing validation branch (lane-launcher.sh:648-649), and the new test cases at lane-launcher.test.sh:375,384-385 exercise both accept-and-launch and flag-passthrough.
• observability/output-format.md's cost-caveat addition is accurate and properly cited.

[claude]

Claude finished @kyle-sexton's task in 1m 5s —— View job

---

Security review

• Gather context (PR diff, changed files)
• Review each changed file for security issues (injection, auth, secrets, dangerous Action patterns)
• Post findings

No security issues found.

This PR is a small, contained fix touching claude-ops docs/config and one launcher script:

• plugin.json — version bump only.
• CHANGELOG.md — prose only.
• skills/changelog/SKILL.md, skills/changelog/context/read-actions.md — repoints the changelog skill's WebFetch target from code.claude.com/docs/en/changelog to the .md sibling (same first-party, hardcoded domain — no user-controlled URL construction), and switches the git log --grep version-detection pattern from a hardcoded v2\.1\. series pin to a generic v[0-9]+\.[0-9]+\.[0-9]+ regex. Both grep arguments remain fully literal/hardcoded strings passed via --grep=, not interpolated from any external/untrusted input, so there's no shell or regex-injection surface here.
• skills/lanes/context/config.md, skills/lanes/scripts/lane-launcher.sh — adds ultracode to VALID_EFFORTS at lane-launcher.sh#L122. The validation at lane-launcher.sh#L648 uses a space-padded substring containment check (" $VALID_EFFORTS " != *" $effort "*), so widening the allow-list to include ultracode doesn't change how the value later reaches claude --effort — it's still constrained to one of six fixed literal words before being passed as a CLI argument (not interpolated into a shell string), so no command-injection surface is introduced.
• skills/lanes/scripts/lane-launcher.test.sh — test-only additions covering the new ultracode value.
• skills/observability/context/output-format.md — prose-only doc addition (cost-estimate caveat).

Nothing here touches authz/access control, secrets/token handling, or GitHub Actions workflow files, and no new external input reaches a shell/eval/path-construction sink.

[github-actions]

Claude has reviewed this PR 4 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8ec46dca9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 58s —— View job

---

Claude finished the code review

• Gather context (PR body, changed files, custom instructions)
• Fetch diff against origin/main
• Review each changed file for correctness / CLAUDE.md alignment
• Post final review

Summary

This is a re-review after the new commit (4d7b163) that addresses the Codex P2 finding on the previous head. I focused on correctness/architecture/tests per the code-review lane split (security is out of scope here — the separate security-lane run already cleared this diff).

The ultracode version-gate fix (4d7b163) is correct and resolves three prior findings:

• Codex's P2 concern — that restart could stop a healthy lane before discovering the CLI can't launch with --effort ultracode — is fixed. I traced the call order in _restart_one: validate_launch_inputs (which now runs the version gate at L688-L694) executes before stop_lane_if_running — a refused lane is never stopped.
• My earlier finding fix: correct plugin-system inaccuracies and harden references #2 (unlinked verification claim) is resolved — config.md#L38 now cites https://code.claude.com/docs/en/cli-reference#cli-flags inline.
• My earlier finding feat: markdown-formatter plugin (pilot migration) #3 (unverifiable older-CLI-fallback claim) is resolved by removal — the launcher now refuses rather than asserting unconfirmed fallback behavior.

The implementation itself (version_at_least / cli_version) is sound: portable awk comparison instead of GNU-only sort -V, memoized per run so multi-lane configs only shell out once, and a malformed/empty claude --version output fails closed to "unknown" (regex-rejected → lane skipped) rather than silently passing. Restart-preflight test coverage (lane-launcher.test.sh:392-412) exercises below-floor skip, at-floor launch, and — the case that actually matters — that a refused restart leaves the running lane's session alive (asserted by checking claude stop never hits the log).

Still open — the changelog .md-channel fix likely doesn't close the bug it's filed against. This was flagged in the prior review round as the one item needing re-verification, and it's unchanged by 4d7b163. I re-fetched https://code.claude.com/docs/en/changelog.md (the exact URL SKILL.md#L31 and SKILL.md#L168 now point at) this session and asked it to enumerate every version header present. It stops at 2.1.186 mid-entry ("[Content truncated due to length...]") and never reaches 2.1.0/2.0.0 — the identical "losing deep versions" symptom CHANGELOG.md#L23-L25 claims this fix resolves, just on the new URL. The .md sibling being smaller and "byte-stable" doesn't matter if it's still well past WebFetch's own size-based summarization threshold (WebFetch's own docs: "results may be summarized if the content is very large"). If that's the actual mechanism, switching the URL doesn't address the root cause, and deep versions will still silently vanish from this skill's fetch/status/diff actions. Given the PR is explicitly gated on a fresh-context verifier pass before merge, this is the one claim that pass needs to either confirm (e.g., show a fetch of an older range resolving correctly, maybe via a different retrieval path) or the changelog entry needs to be corrected to describe a partial mitigation rather than a fix.

Test execution: same sandbox limitation as the prior review — lane-launcher.test.sh requires execution approval unavailable in this context, so I verified the new version-gate logic and its test assertions by inspection only (call order, awk comparison semantics, fail-closed "unknown" path). Worth a real run before merge, per the PR's own "unverified" status.

Everything else checked out

• plugin.json 0.27.0 → 0.27.1 bump matches the new changelog entry.
• changelog status grep generalization (v2\.1\. → -E --grep="CC v[0-9]+\.[0-9]+\.[0-9]+") is correctly scoped; no other file in skills/changelog/ still hardcodes the series pin.
• observability/output-format.md's cost-estimate caveat is accurate and cites its source.

[claude]

Claude finished @kyle-sexton's task in 1m 27s —— View job

---

Security review

• Gather context (PR diff, changed files)
• Review each changed file for security issues (injection, auth, secrets, dangerous Action patterns)
• Post findings

No security issues found.

Reviewed git diff origin/main...HEAD at HEAD 4d7b163 (8 files, all under plugins/claude-ops/). No .github/workflows/* files are touched by this PR, so the pull_request_target/workflow_run/permissions-widening/script-injection surface this lane watches for doesn't apply here.

• .claude-plugin/plugin.json — version bump only.
• CHANGELOG.md, skills/lanes/context/config.md, skills/observability/context/output-format.md — prose-only doc changes.
• skills/changelog/SKILL.md, skills/changelog/context/read-actions.md — repoints the changelog skill's WebFetch target from code.claude.com/docs/en/changelog to the .md sibling. Same first-party hardcoded domain, no user-controlled URL construction — not a new fetch/SSRF surface. The git log --grep pattern also widens from a hardcoded v2\.1\. series pin to v[0-9]+\.[0-9]+\.[0-9]+; both remain literal strings passed via --grep=, never interpolated from external/untrusted input, so no regex/shell-injection surface.
• skills/lanes/scripts/lane-launcher.sh — the interesting part of this diff, so I traced it end-to-end:
  • VALID_EFFORTS widens to include ultracode, but the value still has to match one of six fixed literal words via a space-padded substring check before ever reaching claude --effort as an argv element (not interpolated into a shell string) — no command-injection surface from widening the allow-list.
  • version_at_least() validates its candidate against ^[0-9]+(\.[0-9]+)*$ before ever passing it to awk -v — and awk -v assignment isn't shell-evaluated regardless, so even an unvalidated value couldn't reach a shell sink from there.
  • cli_version() extracts the version from local claude --version output via a fixed grep -oE numeric pattern (falls back to the literal string "unknown"), and that value is only ever used in a [[ ... ]] regex test and an interpolated log message — no eval/sourcing of the probe output.
  • I also traced the ordering Codex flagged in review: _restart_one calls validate_launch_inputs (which now includes the ultracode version gate) before stop_lane_if_running — so a version-gate refusal is not a stop-then-fail-to-relaunch outage; this ordering, plus the corresponding "healthy lane not stopped by a refused restart" test assertion, was added in the second commit (4d7b163) specifically to close that gap. Not a vulnerability in the injection/authz/secrets sense this lane targets, just confirming it's actually closed rather than re-flagging it.
• skills/lanes/scripts/lane-launcher.test.sh — test-only additions (a --version stub branch and new assertions); no production code path.

Nothing here touches authz/access control, secrets/token handling, or GitHub Actions workflow files, and no new external/untrusted input reaches a shell/eval/path-construction sink.

[claude]

Claude finished @kyle-sexton's task in 5m 11s —— View job

---

Claude code review (re-review after commit 97bd84d)

• Gather context (PR body, changed files, custom instructions)
• Fetch diff (git diff f668526..97bd84d, the parent commit prior reviews already covered)
• Review each changed file for correctness / CLAUDE.md alignment
• Verify the two behavior claims this commit re-asserts against a live fetch this session
• Post final review

Scope

Prior review rounds already covered c8ec46d and 4d7b163. This round focuses on what's new in 97bd84d, which was written specifically to answer my previous round's open finding (the changelog .md-channel fix) plus two test-gate weaknesses.

Verified: both re-asserted behavior claims hold up against a fresh fetch

Per CLAUDE.md's fresh-docs mandate, I re-verified both claims this commit changes rather than trusting the prose:

1. Truncation is identical across channels, at 32 versions. I fetched both https://code.claude.com/docs/en/changelog.md and the rendered https://code.claude.com/docs/en/changelog this session. Both return the exact same 32 version headers (2.1.222 → 2.1.186) and cut off with [Content truncated due to length...] mid-entry at 2.1.186. This exactly matches the new CHANGELOG.md#L23-L27 claim ("truncates both channels identically, to the same 32 most-recent versions") — this closes my prior round's open finding. Good catch reframing this as a size/cleanliness win rather than a depth fix.
2. The ultracode pre-2.1.203 fallback behavior is real and correctly cited. I fetched https://code.claude.com/docs/en/model-config#adjust-effort-level and it states verbatim: "Before v2.1.203, --effort ultracode printed Unknown --effort value 'ultracode' and the session started at the default effort." This matches config.md#L38 and lane-launcher.sh#L126-L132 exactly, resolving my prior round's finding feat: markdown-formatter plugin (pilot migration) #3 (previously an unattested assumption).

Verified: both "gates that couldn't fail" are now genuinely armed

• cli_version() memoization bug is real and correctly fixed. The old code set CLI_VERSION_CACHE via v="$(cli_version)" — the whole function ran inside the substitution's subshell, so the cache write never survived past the call, and every lane re-probed claude --version. The fix (lane-launcher.sh#L154-L159) calls cli_version as a bare statement and reads $CLI_VERSION_CACHE directly, avoiding the subshell. The new test (lane-launcher.test.sh#L416-L428) asserts exactly one --version invocation across 3 ultracode lanes — this is a real regression test for the bug, not just a shape check.
• The restart-preflight test previously couldn't fail. It ran with --dry-run, and run() (lane-launcher.sh#L662-L670) short-circuits claude stop under dry-run before it ever reaches the PATH-stub that writes to CLAUDE_LOG — so "no stop in the log" would hold trivially even if _restart_one stopped the lane first. Dropping --dry-run at lane-launcher.test.sh#L412 makes the stop call real (still gated: the below-floor lane never reaches stop_lane_if_running because validate_launch_inputs fails first), so the assertion now has teeth.
• The new dry-run/no-CLI exemption (lane-launcher.sh#L692-L706) is correctly scoped to require_claude's pre-existing "dry runs work with no CLI installed" contract, is keyed on binary absence (not on an unparseable version staying "unknown", which correctly stays refused via version_at_least's regex guard), and the new test (lane-launcher.test.sh#L430-L443) verifies both the "gate not evaluated" message and that the lane still previews.

One new finding: the truncation fix's suggested workaround doesn't actually work via WebFetch

read-actions.md#L9-L13, also SKILL.md#L168

The new text says a version older than the truncation window should be fetched "with a range- or anchor-scoped request, or curl the .md and slice locally." I tested the first option directly this session:

• Asked WebFetch to find only the 2.1.0 entry (a targeted, version-scoped prompt) — still truncated at 2.1.186, never reached 2.1.0.
• Fetched https://code.claude.com/docs/en/changelog.md#2-1-0 (a URL fragment/anchor) — same result, truncated at 2.1.186.

This makes sense given WebFetch's own documented behavior: the size-based summarization applies to the raw fetched content before the prompt is applied, so scoping the ask or the URL fragment doesn't change what content the model actually receives — the truncation already happened upstream. Only the curl-and-slice-locally option (which bypasses WebFetch's summarization entirely) actually reaches deep versions.

As written, an agent following this guidance for an old version might reasonably try the range/anchor-scoped WebFetch route first (it reads as a coequal alternative to curl), get the same truncated response, and only then fall back — wasted effort at best. Since the skill already has shell: bash (SKILL.md#L7), the low-cost fix is to drop the range/anchor-scoped-WebFetch clause and state curl as the only actual mitigation for versions outside the truncation window: Fix this → — low severity (doc-only, and the skill's shell: bash frontmatter means the actual fallback path exists), but worth a quick line edit given this exact claim is what the last two review rounds were gated on.

Test execution

Same sandbox limitation as prior rounds — bash lane-launcher.test.sh requires execution approval unavailable in this context. The author's review comment on 4d7b163 reports a real run passing all 177 cases including the new ones; worth reconfirming after this commit's changes to the same test file before merge, per the PR's own "unverified" status.

Everything else

plugin.json (0.27.1) and the changelog-grep genericization are unchanged from the already-reviewed prior commits and still check out.

[claude]

Claude finished @kyle-sexton's task in 1m 19s —— View job

---

Security review

• Gather context (PR diff, changed files, custom instructions)
• Fetch diff against origin/main, focus on the new commit since the last security-lane pass
• Review each changed file for security issues
• Post findings

No security issues found.

This run adds one new commit (97bd84d) on top of 4d7b163, which the prior security-lane pass (2026-08-05T01:58Z) already cleared. I diffed 4d7b163..97bd84d specifically since that's the only unreviewed delta, then re-confirmed the full f668526..HEAD diff still matches the PR's 8 listed files.

97bd84d changes, reviewed:

• lane-launcher.sh — refactors cli_version() from a printf-and-command-substitution pattern to writing CLI_VERSION_CACHE as a global and having callers read it directly (avoids re-probing claude --version once per lane, since a $(cli_version) substitution would populate the cache inside a subshell and discard it). No new external input enters a shell/eval sink — CLI_VERSION_CACHE is still populated only from the local claude --version output via the same fixed grep -oE numeric pattern, with a fail-closed "unknown" fallback.
• validate_launch_inputs() — adds a DRY_RUN + ! command -v claude branch so a dry run with no claude binary installed previews the lane instead of refusing it (mirrors the existing require_claude exemption). This only widens a preview-only code path (--dry-run); a real launch still requires command -v claude to succeed elsewhere in the script and the version gate still runs unconditionally otherwise. command -v here checks PATH resolution only, not user-controlled input — no injection surface.
• lane-launcher.test.sh — test-only additions (memoization-count assertion, no-CLI dry-run coverage); no production code path affected.
• CHANGELOG.md, SKILL.md, read-actions.md, config.md — prose-only corrections (the truncation-mechanism claim and the ultracode-floor citation URL). No executable surface.

No .github/workflows/* files are touched by this PR, so the pull_request_target/workflow_run/permissions-widening/script-injection surface this lane watches for doesn't apply. Nothing here touches authz/access control, secrets/token handling, or introduces new external/untrusted input reaching a shell/eval/path-construction sink.

[claude]

Claude finished @kyle-sexton's task in 1m 17s —— View job

---

Claude code review (re-review after commit 22e7a00)

• Gather context (PR body, changed files, custom instructions)
• Fetch diff for the new commit since the last review round (97bd84d..22e7a00)
• Review the new commit for correctness / CLAUDE.md alignment
• Post final review

Scope

Prior rounds fully covered c8ec46d, 4d7b163, and 97bd84d. This round covers only what's new: 22e7a00.

22e7a00: trivial, correct, no functional change

The entire diff is a one-word edit inside a comment in lane-launcher.sh#L696:

-    # is unparseable is installed, and stays refused.
+    # is unparsable is installed, and stays refused.

unparsable (not unparseable) is the spelling the repo's typos dictionary (_typos.toml + the typos-format plugin's default corrections) expects — this reads as a fix for a local/CI typos-gate hit rather than a stylistic choice. No code, test, or doc-claim behavior is touched; git diff 97bd84d..22e7a00 --stat confirms exactly 1 file, +1/-1. Nothing to flag here.

Still open from the prior round (unchanged by this commit)

read-actions.md#L9-L13 and SKILL.md#L168 still offer a range-/anchor-scoped WebFetch request as a coequal alternative to curl-and-slice for reaching versions outside the truncation window. My previous round tested this live and found it doesn't work — WebFetch's size-based truncation happens on the raw fetched content before the prompt/anchor is applied, so the only mitigation that actually reaches deep versions is curl. This commit didn't touch these files, so the finding stands as-is; low severity (doc-only, curl fallback still exists via the skill's shell: bash frontmatter).

Everything else

Unchanged from the already-reviewed prior commits (plugin.json version bump, changelog-grep genericization, the ultracode version-gate implementation and its tests) — all previously confirmed and still check out.

Per the PR's own "unverified" status: a fresh-context verifier pass is still needed before merge, per the campaign's producer-never-self-certifies rule — this round only adds the delta review for 22e7a00, it isn't that verifier pass.

[claude]

Claude finished @kyle-sexton's task in 1m 2s —— View job

---

Security review (re-review after commit 22e7a00)

• Gather context (PR diff, changed files, custom instructions)
• Fetch diff against previously-reviewed commit 97bd84d
• Review new changes for security issues
• Post findings

No security issues found.

The only change in 22e7a00 since the last security-lane pass (97bd84d, 2026-08-05T17:07:28Z) is a one-line comment-text fix in lane-launcher.sh:

-    # is unparseable is installed, and stays refused.
+    # is unparsable is installed, and stays refused.

That's a spelling correction inside a # comment above validate_launch_inputs()'s dry-run/no-CLI branch — no executable code, control flow, or string literal changed. I confirmed via git diff 97bd84d..22e7a00 that this is the entire delta (1 file, 1 line changed), and separately confirmed via git diff f668526..22e7a00 --stat that the full PR still matches its stated scope (8 files, +177/-10).

This has zero security surface. All prior security-lane passes on this PR (c8ec46d, 4d7b163, 97bd84d) already found no issues, and nothing in this commit changes that conclusion.

Branch

fix/claude-ops-changelog-series-pin-and-raw-md