Workflow Completeness: self-development README Customizing section uses deprecated bodyContains and omits commentOn/excludeAuthors/author/draft

[kelos-bot]

🤖 Kelos Self-Update Agent @gjkim42

Area: Workflow Completeness

Summary

self-development/README.md is the canonical reference for users adapting the self-development patterns to their own repositories. The "Customizing for Your Repository" section's only webhook-filter example still uses the deprecated bodyContains field and silently omits every modern filter field that the actual TaskSpawners depend on (bodyPattern, commentOn, excludeAuthors, author, draft, excludeBodyPatterns). A user who copies the example verbatim ends up with the now-deprecated configuration shape and has no visibility into the safety filters every shipped spawner uses.

This is distinct from the existing open README issues:

• Workflow Completeness: self-development README.md has five factual inaccuracies against actual TaskSpawner definitions #890 and Workflow Completeness: self-development README.md has three additional inaccuracies post-#890 #1019 enumerate factual inaccuracies in TaskSpawner descriptions (triage trigger, pr-responder trigger, make test claim, inline-AgentConfig list); neither touches the Customizing section.
• Workflow Completeness: kelos-pr-responder filter no longer enforces generated-by-kelos label, contradicting README in three places #1109 covers the pr-responder label/filter mismatch in README lines 19/133/137; not the example snippet.
• Docs: integration.md GitHub Webhooks section uses deprecated bodyContains — bodyPattern/excludeBodyPatterns and {{.Schedule}} missing #1120 raises the same bodyContains deprecation against docs/integration.md — a different file. PR self-development: migrate bodyContains to bodyPattern in spawner configs #1127 explicitly documented that the README example was kept out of its scope ("Out of scope (per the issue): The README.md example snippet — kept aligned with the issue's enumerated *.yaml scope.").
• Configuration Alignment: self-development TaskSpawners still use deprecated bodyContains in 10 filter entries #1125 (closed by self-development: migrate bodyContains to bodyPattern in spawner configs #1127) migrated the deprecated field only inside self-development/*.yaml.

So self-development/README.md is the last bodyContains survivor in this directory and it stands as a direct contradiction of every TaskSpawner sitting next to it.

Findings

1. Deprecated bodyContains in the only filter example (line 407)

self-development/README.md lines 397–410:

spec:
  when:
    githubWebhook:
      repository: your-org/your-repo
      events: [issue_comment]
      filters:
        - event: issue_comment
          action: created
          bodyContains: /kelos pick-up   # <-- deprecated
          labels: [your-label]
          state: open

The Kelos API marks bodyContains deprecated in favor of bodyPattern (api/v1alpha1/taskspawner_types.go:433-438):

// BodyContains filters by case-sensitive substring match on the
// comment/review body.
// Deprecated: use BodyPattern instead, which supports regex.

All six webhook-driven TaskSpawners in this directory now use bodyPattern after #1127. The verifier holds:

$ grep -c bodyContains self-development/*.yaml
self-development/kelos-api-reviewer.yaml:0
self-development/kelos-config-update.yaml:0
self-development/kelos-fake-strategist.yaml:0
self-development/kelos-fake-user.yaml:0
self-development/kelos-image-update.yaml:0
self-development/kelos-planner.yaml:0
self-development/kelos-pr-responder.yaml:0
self-development/kelos-reviewer.yaml:0
self-development/kelos-self-update.yaml:0
self-development/kelos-squash-commits.yaml:0
self-development/kelos-triage.yaml:0
self-development/kelos-workers.yaml:0
$ grep -c bodyPattern self-development/README.md
0

The example is the only bodyContains reference left in self-development/.

2. Filter fields used by every spawner are absent from the README

The Customizing section's example presents only three filter fields (bodyContains, labels, state). The shipped TaskSpawners rely on five more — none of which are documented anywhere in self-development/README.md:

Field	Used by	Purpose actually served
excludeAuthors (top-level under githubWebhook)	api-reviewer, planner, pr-responder, reviewer, workers	Filter out the agent's own bot comments (kelos-bot[bot]) — prevents trigger loops. Added by PR #1100 to break the self-development loop.
commentOn	pr-responder (PullRequest), workers (Issue)	Scopes issue_comment events to issues only or PRs only; GitHub fires issue_comment for both. Critical for keeping planner/workers off PRs and pr-responder off issues.
author	api-reviewer, planner, pr-responder, reviewer, squash-commits, workers (gjkim42)	Restricts triggers to maintainer-authored comments — the actual maintainer-approval gate.
draft	pr-responder (draft: false)	Skips draft PRs.
excludeBodyPatterns	(not yet used, but available since #1081 era)	Regex exclusion list — paired with bodyPattern.

A reader of the README who copies the example will:

1. Use a now-deprecated field, generating no warning but cementing technical debt.
2. Have no maintainer-author gate, so any GitHub user posting /kelos pick-up can fan out an Opus task on their repo.
3. Have no excludeAuthors exclusion, so as soon as the spawned agent comments /kelos pick-up-like text (e.g., echoing a maintainer's comment), the spawner will re-trigger.
4. Have no commentOn, so /kelos pick-up on a PR comment will trigger a spawner that was meant for issues (or vice versa).

Items 2 and 3 in particular are the same hardening problems the self-development pipeline itself has had to address over the last quarter (#1098/#1100 for excludeAuthors, #1080/#1081 for commentOn, the maintainer-author gates introduced piecemeal).

3. The Customizing section does not point users at the more complete reference

docs/reference.md documents the full GitHubWebhookFilter field set (modulo #1095 / #1120 deprecation-notice gaps already filed). The README's Customizing section does not link to docs/reference.md or any other authoritative source, so a user reading only self-development/README.md has no path to the unfiltered field list.

Proposed Fix

1. Replace bodyContains: /kelos pick-up on line 407 with bodyPattern: /kelos pick-up and add a one-line comment noting that bodyContains is deprecated.

2. Extend the example to show excludeAuthors (top-level under githubWebhook) and the per-filter fields commentOn, author, and draft — using values consistent with the shipped spawners. A representative example:

   spec:
     when:
       githubWebhook:
         repository: your-org/your-repo
         excludeAuthors:
           - your-bot[bot]            # avoid self-trigger loops
         events: [issue_comment]
         filters:
           - event: issue_comment
             action: created
             bodyPattern: /kelos pick-up
             commentOn: Issue          # or PullRequest, depending on spawner
             author: your-maintainer   # maintainer-approval gate
             labels: [your-label]
             state: open

3. Add a short prose paragraph (or a new bullet under "Update the webhook repository and filters") summarising the field set with one-line descriptions, and link to docs/reference.md#githubwebhookfilter for the canonical reference. Mirror the wording style of the existing "template variables" prose so the section stays consistent.

4. Optional but recommended: add excludeBodyPatterns to the documented set with a one-line mention so users discover the regex-exclusion option that pairs with bodyPattern.

Verification

Once fixed:

$ grep -c bodyContains self-development/README.md
0
$ grep -E 'bodyPattern|commentOn|excludeAuthors|author:|draft:' self-development/README.md | wc -l
# should be > 0

Not covered by existing issues

• Workflow Completeness: self-development README.md has five factual inaccuracies against actual TaskSpawner definitions #890, Workflow Completeness: self-development README.md has three additional inaccuracies post-#890 #1019, Workflow Completeness: kelos-pr-responder filter no longer enforces generated-by-kelos label, contradicting README in three places #1109 cover other distinct README inaccuracies — none touch the Customizing example or the filter-field gap.
• Docs: integration.md GitHub Webhooks section uses deprecated bodyContains — bodyPattern/excludeBodyPatterns and {{.Schedule}} missing #1120 covers the same deprecation in docs/integration.md (different file, different audience).
• Configuration Alignment: self-development TaskSpawners still use deprecated bodyContains in 10 filter entries #1125 (closed by self-development: migrate bodyContains to bodyPattern in spawner configs #1127) intentionally scoped out the README example.

[kelos-bot]

🤖 Kelos Task Status

Task kelos-triage-issues-c299f0d7dc1a has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs
Priority: priority/important-longterm — Misleading example in the canonical self-development reference can lead users to copy a deprecated, less-safe webhook filter (no maintainer gate, no self-trigger exclusion), but the README is adopter-facing rather than runtime-blocking.
Actor: actor/kelos — Concrete, narrowly scoped docs change to a single file with objectively verifiable acceptance criteria (grep -c bodyContains self-development/README.md → 0; new fields present), no API or design decisions required.

Status: STILL VALID

Evidence:

• self-development/README.md:407 still contains bodyContains: /kelos pick-up. Verified: grep -c bodyContains self-development/*.yaml self-development/README.md reports 0 across all spawner YAMLs and 1 in README.md — i.e., the README is the last bodyContains survivor in self-development/.
• The Customizing example (lines 397–410) shows only bodyContains, labels, state — none of bodyPattern, excludeAuthors, commentOn, author, draft, or excludeBodyPatterns appear anywhere in self-development/README.md (verified by grep), despite every shipped spawner relying on the maintainer-author + commentOn + excludeAuthors triad.
• API deprecation notice still present at api/v1alpha1/taskspawner_types.go (BodyContains deprecated in favor of BodyPattern).
• PR self-development: migrate bodyContains to bodyPattern in spawner configs #1127 (merged 2026-05-12) migrated only the self-development/*.yaml files and explicitly noted the README example was out of scope.
• No merged PR references Workflow Completeness: self-development README Customizing section uses deprecated bodyContains and omits commentOn/excludeAuthors/author/draft #1131. Open PR docs: fix github webhook example fields #1119 touches examples/10-taskspawner-github-webhook/taskspawner.yaml and docs/integration.md — different files, does not address self-development/README.md.

Duplicates found: None.

• Workflow Completeness: self-development README.md has five factual inaccuracies against actual TaskSpawner definitions #890, Workflow Completeness: self-development README.md has three additional inaccuracies post-#890 #1019 — other README inaccuracies; neither touches the Customizing webhook-filter example or the missing-fields gap.
• Workflow Completeness: kelos-pr-responder filter no longer enforces generated-by-kelos label, contradicting README in three places #1109 — pr-responder label/filter mismatch in README narrative; not the example snippet.
• Docs: integration.md GitHub Webhooks section uses deprecated bodyContains — bodyPattern/excludeBodyPatterns and {{.Schedule}} missing #1120 — same bodyContains deprecation but in docs/integration.md (different file, different audience).
• Configuration Alignment: self-development TaskSpawners still use deprecated bodyContains in 10 filter entries #1125 (closed by self-development: migrate bodyContains to bodyPattern in spawner configs #1127) — scope was YAML-only; README explicitly excluded.

Recommendation: KEEP OPEN