Repository navigation
Description
Filed by AI on operator direction (attended session, 2026-07-24). Research verified empirically — see Evidence below.
Category: design · Source: operator observation during a live work-items:work-loop cycle, 2026-07-24
Problem
The loop-lane telemetry contract (convention §4, "Telemetry comment (#502)") stores each lane's durable state on a permanently-open GitHub Issue (Lane telemetry: <lane>), one per lane, carrying a single sentinel-marked comment edited in place.
The operator flagged this as a design smell while watching a lane run: the telemetry issues are permanent non-work items squatting in the real Issues backlog with no cleanup path. They are excluded from every drain/frontier evaluation by title contract, but they still appear in the default Issues view forever, and their open state — the signal a human reads as "this is outstanding work" — means the opposite here ("this lane is operating"). Three exist today: #1248 (work-loop), #1214 (babysit-loop), #1198 (attend-queue), and the count grows linearly with lanes.
This is a storage-mechanism problem, distinct from #1221, which fixes only how cycle reports describe the existing surface (correct artifact noun, standing convention anchor). #1221 makes the current design legible; this issue reconsiders whether it is the right surface at all.
Direction
Move loop-lane telemetry from a permanently-open Issue to a categorized GitHub Discussion, keeping the existing single-sentinel-comment-edited-in-place design, driven via gh api graphql.
Rationale (all empirically verified, see Evidence):
- Discussions is the only candidate that keeps the human-repliable, notified, edit-in-place comment thread the ratification workflow depends on while moving the object entirely off the Issues backlog — Discussions is a separate GitHub surface/tab, not a filtered Issues view.
- Headless reliability equals Issues provided automation targets the stable GraphQL mutations (
createDiscussion,addDiscussionComment,updateDiscussionComment) rather than thegh discussionCLI porcelain, which the shipped binary and its upstream source both mark preview, "subject to change without notice" (added 2026-06-10). This requires no new habit: the lanes already bypass porcelain for rawgh apiPATCH. markDiscussionCommentAsAnsweris a genuine gain — a native "this reply is ratified" primitive with no Issues equivalent, directly useful to thekind=ratify-c3flow in/work-items:attend-queue.
Explicitly rejected framings:
- Pinning is a red herring — capped and web-UI-only on both surfaces (Discussions 4/repo and 4/category; Issues 3/repo), with no pin mutation in the GraphQL schema. Lanes must be found by title/category search, exactly as the status quo finds its Issue today.
- "Issues are wrong for automation" is too broad — GitHub's own IssueOps engineering blog blesses Issue-driven automation. The real, narrower defect is a never-closable Issue in the default backlog view, which Discussions fixes by being a separate surface.
Rejected alternatives: Actions/repo configuration variables (no comment/reply/notification mechanism at all — disqualifying alone, despite generous 48 KB/variable, 500/repo limits); Gist (flat comments, repo-indirection, no offsetting gain); bare git-tracked state branch (best audit trail of the five, but no reply channel).
Deferred, not excluded: a Discussion + git-tracked-branch hybrid, if a truly diffable audit trail ever becomes a hard requirement. It is not one today — and note neither Issue-comment nor Discussion-comment edit history is exposed via any API, so the status quo has no audit trail either. Trigger: a requirement for value-level state diffs.
Blast radius
docs/conventions/loop-lane/README.md§4 — the telemetry contract is the owning surface; the tracking-item shape and theLane telemetry: <lane>title contract change here.- Three lane
SKILL.mdbodies carrying the inlined upsert (an installed plugin cannot invoke a sibling plugin's script, so each inlines it):work-items/work-loop,work-items/attend-queue,source-control/babysit-loop. All three inline the samegh apiREST comment upsert and all three must move to the GraphQL mutation shape together — the marker/sentinel contract is byte-shared across lanes. claude-opslanes/scripts/telemetry-upsert.sh(canonical interim home of the contract) and its.test.sh.claude-opsmorning-brief/scripts/morning-brief.sh— the compatible reader of the same surface; a writer-only migration silently breaks the brief.- Non-GitHub providers: the contract already degrades to "carry telemetry in the lane's cycle report" when the bound provider is not
github. Discussions narrows the GitHub-native path further (Discussions is a GitHub-only concept with no REST API), so the degradation clause needs a re-read, not just a copy. github-iac—has_discussionsis a repository setting; per the operator's standing convention it is a Pulumi-managed change in the relevantgithub-iacrepo, never a runtimegh repo editcall embedded in a plugin. Currently disabled on all 14 sampledmelodic-softwarerepos.- Migration of the three existing telemetry issues (Lane telemetry: work-loop #1248, Lane telemetry: babysit-loop #1214, Lane telemetry: attend-queue #1198) — content moves; the issues close with a pointer.
Sequencing constraint
The IaC enablement lands first (repos cannot host a Discussion until has_discussions is true), and the reader (morning-brief) must handle both surfaces during the transition, or be cut over in the same change as the writers.
Evidence
Research run 2026-07-24 via the discovery:research protocol — 5+ distinct tool types including live gh api graphql mutations against a throwaway personal repo (full create → comment → edit-in-place → delete round-trip), gh CLI --help capture, upstream cli/cli source fetched via gh api repo-contents, and direct fetches of docs.github.com. Outcome gate passed on all 8 binary criteria. Full evidence table, per-claim source tiers, conflicts, and gaps:
Posted in full on this issue: research evidence comment. It was produced as a machine-local memory-tier artifact, so it is reproduced here to keep the evidence durable and reviewable rather than tied to one workstation.
Open verification gaps carried forward:
- All empirical CRUD testing ran against a personal-account repo, not an org repo — verify the same mutations against an actual
melodic-softwareorg repo before rollout. - Untested whether an org-level policy can block enabling Discussions for member repos.
Relations
- loop-lane telemetry: cycle reports misname the surface ('telemetry PR') and never restate the edited-in-place convention — operator-legibility rules #1221 — sibling on the same surface, report/legibility path (this issue is the storage-mechanism path); loop-lane telemetry: cycle reports misname the surface ('telemetry PR') and never restate the edited-in-place convention — operator-legibility rules #1221's "standing one-line anchor" text will need rewording for whatever surface this lands on.
- ops: loop-lane telemetry — running per-lane status (babysit / triage / work) #502 — the umbrella the telemetry block is named for.
- babysit lane telemetry edit posts literal @path body instead of file content (#502 observability fail-open) #943, guardrails/telemetry: harden telemetry-upsert.sh with post-write read-back verification + canonicalize @path-as-body anti-pattern rule #952 — telemetry-upsert write-path defects on the current (REST) implementation; a migration to GraphQL mutations should confirm whether each still applies or is obsoleted.
Activity
kyle-sexton commentedon Jul 24, 2026
This was generated by AI on operator direction.
Sequencing head landed as a PR: melodic-software/github-iac#219 enables
HasDiscussionson this repository through the governed-repository spec seam (dotnet buildclean, 56/56 tests pass, lefthook clean).That PR is a blocking dependency for the plugin-side work here — no repository can host a telemetry discussion until
has_discussionsis true, and the carried-forward verification gap (GraphQL mutations proven only against a personal-account repo) cannot be closed against this org repo until it deploys.Remaining work on this issue, in order:
createDiscussion/addDiscussionComment/updateDiscussionCommentagainst this repository, closing gap 1.docs/conventions/loop-lane/README.md§4 — the owning surface for the tracking-item shape and theLane telemetry: <lane>title contract.work-items/work-loop,work-items/attend-queue,source-control/babysit-loop.claude-opslanes/scripts/telemetry-upsert.sh+ its.test.sh.claude-opsmorning-brief/scripts/morning-brief.sh— the reader; cut over with the writers or teach it both surfaces, or the brief silently breaks.Steps 2-5 are authorable before #219 merges but not verifiable end-to-end until it does.
kyle-sexton commentedon Jul 24, 2026
RESEARCH.md — loop-lane telemetry durable-state mechanism
Task restatement
Vet whether GitHub Discussions is the right mechanism for a Claude Code plugin's "loop-lane
telemetry" durable state: a small JSON state block + human-readable cycle report, one lane
per repo, edited/updated every drain cycle, must survive session death, and needs a
human-repliable channel for ratification replies. Status quo: one permanently-open GitHub
Issue per lane ("Lane telemetry:
<lane>"), one sentinel-marked comment edited in place viagh apiPATCH. Flagged smell: permanent non-work Issues clutter the real Issues backlogforever, with no cleanup path.
Candidates compared: (a) status-quo Issue, (b) pinned/categorized Discussion, (c) Actions/repo
variable (
gh variable), (d) git-tracked state file on a dedicated branch, (e) Gist.Non-interactive / no-project-root note: this session's working directory is not a git
repo, so per the topic-docs no-project-root fallback this artifact is written to the
plugin-data surface rather than a repo-local
.work/.CLAUDE_PLUGIN_DATAwas set to astale value from an unrelated plugin (
codex-openai-codex) in this environment, so the pathwas constructed by hand from the observed
~/.claude/plugins/data/<plugin>-<marketplace>/convention:
C:/Users/KyleSexton/.claude/plugins/data/discovery-melodic-software/topic-docs/loop-lane-telemetry-storage/RESEARCH.md.Summary
No single candidate cleanly satisfies both halves of the requirement (durable JSON state
block + human-repliable ratification channel) — the task bundles two different capabilities
that the status-quo Issue currently fuses together. Of the five candidates, GitHub
Discussions is the correct swap for the container (b): it is the only mechanism that keeps
the human-repliable, notifiable, edit-in-place comment thread the workflow needs while
moving it off the real Issues backlog entirely (Discussions is a separate GitHub surface/tab,
not a filtered view of Issues). It can be driven headlessly with equal reliability to Issues
provided automation targets the stable GraphQL mutations directly via
gh api graphql(exactly how the status quo already scripts the sentinel-comment PATCH) rather than the new
gh discussionCLI porcelain, which is explicitly marked preview/unstable as of thisresearch. Pinning is a red herring — it's capped, web-UI-only to set on both Issues (3) and
Discussions (4), and unnecessary since lanes are found by title search/category exactly as
Issues are found today.
Evidence table
gh api repos/kyle-sexton/autonomy-demo-scratchshowshas_discussions/has_issuesas plain REST fields, but discussion CRUD only exists as GraphQL mutations (schema introspection, this turn); WebFetch ofdocs.github.com/en/restshows 45 top-level categories, none named "Discussions"createDiscussion,addDiscussionComment,updateDiscussionComment,deleteDiscussion,closeDiscussion,reopenDiscussion,markDiscussionCommentAsAnswerall exist and workgh api graphqlcalls this turn: created discussion #65 onkyle-sexton/autonomy-demo-scratch, added a comment, edited it in place (updateDiscussionComment), then deleted the discussion — full round-trip succeededgh discussion comment <id> --edit, targeting an arbitrary comment by ID/URL — a capabilitygh issue commentporcelain lacks (gh issue commentonly offers--edit-last, which edits the current user's last comment, not an arbitrary comment by ID; status quo bypasses this gap entirely by usinggh apiPATCH directly, not porcelain)gh discussion comment --helpandgh issue comment --helpboth run this turn; GraphQLupdateDiscussionCommentindependently confirmed the same editgh discussioncommand group is explicitly marked preview, "subject to change without notice", and was added only ~6 weeks before this research (2026-06-10)gh discussion --helpoutput this turn: "Working with discussions in the GitHub CLI is in preview and subject to change without notice."; upstream sourcepkg/cmd/discussion/discussion.gofetched viagh api repos/cli/cli/contents/...this turn shows the same string plusShort: "Work with GitHub Discussions (preview)";gh search prs "discussion command" --repo cli/cli --mergedshows PR #13541 "feat: adddiscussioncommand set" closed 2026-06-10gh discussion(2026-06-10) does not mention "preview"/"experimental" — a marketing/docs vs. shipped-CLI discrepancygithub.blog/changelog/2026-06-10-list-view-and-create-discussions-in-github-cli/this turn — no preview/experimental language foundDiscussion-type schema introspection this turn shows no pin mutation (only a read-onlyRepository.pinnedDiscussionsconnection); WebFetch ofdocs.github.com/en/discussions/managing-discussions-for-your-community/managing-discussionsthis turn: "You can pin up to four important discussions above the list of discussions for the repository or organization" / "up to four... in a specific category," steps are UI-onlydocs.github.com/.../pinning-an-issue-to-your-repositorythis turn: "You can pin up to three important issues above the issues list in your repository"; no API/CLI method documentedmelodic-softwarerepos; the toggle is reachable headlessly viagh repo edit --enable-discussions(addedcli/cliPR #6903, shippedghv2.22.0) or RESTPATCH /repos/{owner}/{repo}has_discussionsfield — not web-UI-onlygh repo list melodic-software --json hasDiscussionsEnabledthis turn (14/14 false);gh repo edit kyle-sexton/autonomy-demo-scratch --enable-discussionsthen--enable-discussions=falseboth executed and verified viagh api repos/.../ -q .has_discussionsthis turn (false → true → false)docs.github.com/en/actions/reference/workflows-and-actions/variablesthis turn, quoting exact limit sentencesgh variable --helpthis turn confirmsset/get/list/deleteonly, no comment verbdocs.github.comaudit-log-events pages (Tier 2 corroboration; not directly confirmed with a fetched exact event name this turn)PATCH /gists/{gist_id}/comments/{comment_id}(edit in place), comment body capped at 65,535 chars; gists have native revision/version history; comment notifications shipped 2019docs.github.com/en/rest/gists/commentsthis turn (endpoint list +maxLength: 65535from the schema); WebSearch corroboration ofgithub.blog/changelog/2019-05-08-gist-notifications/communitydiscussions and third-party tool issue trackers hitting the exact same 65536 error message; WebFetch ofdocs.github.com/en/rest/issues/commentsthis turn confirms thePATCHendpoint (status-quo mechanism) exists but the fetched page excerpt did not itself state the numberdocs.github.com/en/discussionsanddocs.github.com/en/issues/.../about-issuesthis turn, both quoted verbatimgithub.blog/engineering/issueops-automate-ci-cd-and-more-with-github-issues-and-actions/this turn, quoted verbatim; page explicitly does not discuss backlog-clutter mitigationdocs.github.com/en/rest/issues/commentsand the GraphQLDiscussion/DiscussionCommenttype introspection this turn — no revision/history field present in eithersearch(type: DISCUSSION, ...)GraphQL query and nativegh discussion list --search/--category/--labelboth work for finding a lane's discussion by title — parity with how the status quo finds its Issue by titlegh api graphqlsearch query this turn (discussionCount:1, matched by title substring);gh discussion list --helpthis turn shows-S/--search,-c/--category,-l/--labelflagsgh search(the general search porcelain) does not support a Discussions type — only issues/PRs/repos/commits — a real capability gap in the general search CLI, mitigated bygh discussion listand raw GraphQLsearch(type: DISCUSSION)gh search prs --state mergedthis turn errored, revealing valid--statevalues are only `{open, andgh search` subcommands are issues/prs/repos/commits/code only (observed from command family this session)Conflicts
gh discussion(2026-06-10) presents it as a shipped, unqualified feature; the CLI binary itself and its
upstream source both say, verbatim, "in preview and subject to change without notice."
Resolution: the primary (shipped code, fetched this turn) wins — treat
gh discussionaspreview-grade for production automation. This does not block the recommendation because the
underlying GraphQL mutations it wraps are the same stable, long-standing GA surface the
status quo already uses via
gh api.Discussion thread" as the candidate, but pinning turns out to be a cosmetic, capped (4),
web-UI-only affordance that contributes nothing to headless find/automation — Issues have
the identical constraint (cap 3, UI-only). Resolution: don't design around pinning at all;
use category + title search, matching the status quo's existing find-by-title pattern.
The design-smell framing implies Issues are simply the wrong tool for automation. GitHub's
own engineering blog explicitly blesses Issues-as-automation-interface (IssueOps). The real
problem the smell report identifies is narrower and correct: a permanently-open,
never-closable Issue clutters the default backlog view — that's a visibility/lifecycle
problem, not a "was it legitimate to automate an Issue at all" problem. Discussions solves
the visibility problem (separate surface from Issues) without requiring anyone to accept
that automating a work-tracking object was wrong in principle.
Gaps
captures repo-variable value changes (vs. just an update event) was not confirmed with a
directly fetched primary this turn — Tier 2 (WebSearch synthesis) only. Residual risk: low,
since this candidate is already disqualified for the human-repliable half regardless.
obvious revision field via GraphQL introspection and the REST issue-comments doc, but did
not exhaustively enumerate every GraphQL type/field or the audit-log event catalog to rule
out an indirect path (e.g., a webhook
editedevent stream reconstructed externally). Ifthe maintainer later needs a true diffable audit trail, re-verify this before ruling it out
permanently; git-tracked state (candidate d) sidesteps the question entirely.
limits came from WebSearch corroboration, not a page fetched directly this turn (the fetched
docs.github.com/en/rest/gists/commentspage covered comments, not gist file size). Notpursued further since gist was already ruled out on structural grounds (flat comments, extra
indirection) independent of size.
centrally disable the Discussions feature (analogous to Actions policies) for member repos
was not researched — relevant only if
melodic-softwarehas such a policy; the empiricaltest succeeded on a personal-account repo, not an org repo, so the org policy surface is
unverified.
Recency status
ghCLI (gh --version)gh discussioncommand groupghv2.94.0 / merged 2026-06-10 (PR #13541) — ~6 weeks old; treated as very-active/preview surface, 14-day gate does not strictly apply since it's a net-new feature not a churning one, but its preview status is itself the findingdocs.github.com/en/graphql/overview/changelog/2026checked this turn; no Discussions-breaking changes found for 2026; GitHub's stated policy is 3 months' notice before any breaking GraphQL changegh variable)docs.github.com/en/rest) — current as of this sessionProject fit
settings changes go through the relevant
github-iacrepository via Pulumi, not ad hocmutation. Enabling Discussions per repo (
has_discussions) is a repo setting — if thisrecommendation is adopted, the enable-per-lane-repo step belongs in the Pulumi-managed
github-iacprovisioning path, not as a runtimegh repo edit --enable-discussionscallembedded in the plugin's lane-provisioning logic. This turn's empirical test used
gh repo editdirectly only because that's the fastest way to verify capability, not as asuggested production mechanism.
gh apiover porcelain, already the plugin's own pattern. The status quo already drivesthe sentinel comment via
gh apiPATCH rather thangh issue comment --edit. That sameposture — target the stable API surface directly — is exactly what resolves the CLI-preview
conflict for Discussions: use
gh api graphqlmutations, not the previewgh discussionporcelain, for anything the loop depends on.
or behavior to account type (personal vs. org) beyond the standard enable-toggle and the
unverified org-policy question in Gaps ci: onboard to the CI platform (ci-workflows + standards) #4 — worth a one-time check against an actual
melodic-softwareorg repo before rollout, since all empirical CRUD testing here was doneagainst a personal-account repo (
kyle-sexton/autonomy-demo-scratch) to avoid mutatingorganization repositories without explicit authorization.
Outcome gate result
gh api-over-porcelain posture)Gate result: PASS.
Final recommendation
Move loop-lane telemetry from a permanently-open Issue to a categorized GitHub Discussion,
keeping the existing single-sentinel-comment-edited-in-place design, and drive it via
gh api graphql— not the previewgh discussionCLI.Why this beats every alternative for this exact job:
the ratification workflow needs and removes the object entirely from the Issues backlog
surface (Discussions is a separate tab, not a filtered/labeled view of Issues) — directly
fixing the flagged smell without giving up the capability the status quo exists to provide.
mutations directly (
createDiscussion,addDiscussionComment,updateDiscussionComment,closeDiscussion) — all confirmed working this turn, all part of the long-standing GAGraphQL schema, not the 6-week-old preview CLI wrapper. This requires no new habit: the
plugin already drives Issues via
gh apirather than porcelain.markDiscussionCommentAsAnsweris a genuine, unplanned upgrade for the ratificationuse case — a native "this reply is the accepted one" primitive Issues has no equivalent for
(today's Issue-based design would have to fake this with a label or comment-parsing
convention).
(
has_discussionsvia REST/gh repo edit) — and per this user's own convention, thatenablement belongs in the Pulumi-managed
github-iacrepo alongside other GitHub reposettings, not embedded as a runtime call in the plugin itself.
capped, cosmetic, and web-UI-only on both Issues and Discussions; find the lane's
discussion by title search or a dedicated category instead, which is a drop-in replacement
for the current find-Issue-by-title logic.
Explicitly not recommended alone: Actions/repo variables (no reply channel — disqualifying
on their own), Gist (flat comments + extra repo-indirection — structurally weaker than
Discussions for no offsetting gain), a bare git-tracked state branch (no reply channel at all).
Deferred, not excluded: if a true diffable audit trail of state-block changes ever becomes
a hard requirement (it is not part of today's stated need), a hybrid — Discussion for the
human-repliable report, a git-tracked branch file for the versioned JSON state block — is the
documented escape hatch (see Gaps #2), triggered only if that need materializes.
Next-stage handoff
Settled facts (usable directly by a planning step):
gh discussionCLI porcelain is preview/unstable; usegh api graphqlinstead.melodic-softwarerepos; toggle is scriptable, not UI-only.Open decisions for the planning step:
github-iac/Pulumi provisioning path now, or accept a temporarygh repo editruntime call as a stopgap.melodic-softwareorgrepo before rollout, since empirical testing here was confined to a personal-account repo.
markDiscussionCommentAsAnswershould become part of the ratification protocolitself (e.g., ratifying = marking the sentinel or a reply as the answer) or remain unused in
favor of the existing sentinel-marker convention.
kyle-sexton commentedon Jul 24, 2026
This was generated by AI on operator direction.
Status at session close.
Dependency PR melodic-software/github-iac#219 is green and ready to merge — 28 checks passing on head
2cf4dc7,mergeStateStatus: CLEAN, automated review verdict "Correct, minimal, and honest about what it doesn't yet prove. Ready to merge." Nothing on it is waiting on further authoring; it needs a human merge and a Pulumi deploy.Nothing in this issue's scope has been implemented yet — no plugin-side branch exists. Steps 2-6 of the plan above are unstarted, and step 1's merge is the gate for steps 1, 2, and 7.
Resuming from a cold start needs only this issue. The design decision, blast radius, rejected alternatives, sequencing constraint, and the full research evidence (including per-claim source tiers and the two carried-forward verification gaps) are all recorded here rather than in any session transcript or local artifact.
Recommended resumption order once #219 deploys:
telemetry-upsert.sh+ test, and themorning-briefreader.fix(lanes): key telemetry state per lane instance, not per lane type (#…
kyle-sexton commentedon Aug 13, 2026
Frontier disposition (drain session)
Ruling: Close as not planned.
Telemetry storage-mechanism reconsideration (Issues vs Discussion) is advisory; permanently-open Issues remain the shipped convention.
Re-open trigger: When lane telemetry issue volume blocks tracker usability.