Repository navigation
Maintenance scan: a scheduled read-only lens fan-out merged into one rolling digest issue - #334
Conversation
…ry's default branch, merged into one rolling digest issue The reviewer's machinery pointed at a whole tree on a schedule (docs/design/reviewer-infra.md, "Maintenance scan"). New: - maintain.py: the lens library (one lens per digest section, general for the whole checklist), the scan brief, the digest and stub renderers, and run_maintenance_scan, which emits the same envelope the reviewer does. - maintain_agent_cli (one read-only lens session over REVIEW_CHECKOUT, emit only; fails closed to a stub on a missing tree, an unsanitizable tree or a backend without its key) and maintain_post_cli (the write token: creates the "Maintainer digest" issue or rewrites the bot's own marker issue and comments so watchers are told; never rewrites a person's issue). - roles.maintainer_spec: the reviewer's tools and verdict shape with a tree-sized budget; GitHubClient.update_issue. - maintenance-agent.yml (reusable: lens matrix -> summarizer -> post, with the reviewer's key discipline) and maintenance.yml (the kernel's weekly caller; any repository copies it). - result_from_data carries a sanitized category so the summarizer's merged findings keep their digest section; the summarizer brief says to keep it. Nothing is changed or opened automatically: the digest issue carries no steward label, so intake and the steward ignore it, and a person turns a mechanical item into a work order when they want it done. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Round 1 — reviewed head 4037081a — reviewer summarizer:hermes/gpt-5.6-terra over coverage+credentials+deployment+general+lifecycle+prose.
terra
Advisory findings from outerloop — the code owner decides. Reply to disagree; the outerloop:no-review label opts this PR out.
Verdict: 2 blocking, 5 advisory.
6 findings attached to the lines below.
Advisory (non-blocking):
- Maintenance section categories are converted to other. [coverage+deployment+general+lifecycle+prose] The maintenance scan emits section categories such as pathways and docs, but verdict validation preserves only verifier.CATEGORIES and converts other values to other, collapsing every digest item into the other section rather than grouping it by lens. (
src/outerloop/syscall.py:542; high confidence)
Verdict: two blocking issues require remediation before merge: the lens session is exposed to the checkout deploy key, and the rolling-digest lookup can overwrite a marked issue created by another bot. Non-blocking changes: preserve maintenance section categories through verdict validation and cover that real path in tests; remove the 300-open-issue lookup ceiling; explicitly check out the default branch for manual runs; and correct the install-guide behavior. Rejected as duplicates (merged): the [coverage], [deployment], [general], and [prose] category reports restated the [lifecycle] validation defect; the [credentials], [general], and [prose] branch reports restated the [deployment] checkout-ref defect. No findings were rejected as mistaken.
…solved default-branch commit, the poster's own issue only, sections survive the verdict reader - maintenance-agent.yml drops the checkout_ssh_key secret (the kernel is public; a session job never sits next to a deploy credential) and gains a resolve job: the default branch's head is looked up once and every lens checks out, scans and links that commit, whatever ref a manual run was dispatched from. - The digest lookup asks GitHub for the posting login's own open issues (list_open_issues(creator=...)) and re-checks the author: another bot's or a person's marker issue is never rewritten, and the lookup no longer depends on the first 300 open issues. bot_login is a workflow input (default the workflow's own token). - read_verdict keeps a maintenance section as a category (unknown values still clamp to other); an end-to-end test commits a verdict through the syscall channel and reads it back into the digest. - install.md says what the scan opens: one issue, no code, no work orders. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
1 participant
What
A weekly maintenance digest, built as a type within the advisory-review surface (design:
docs/design/reviewer-infra.md, "Maintenance scan").maintenance-agent.yml(reusable): one read-only lens session per digest section over a checkout of the calling repository's default branch (pathways,duplication,structure,upgrades,tests,performance,docs, plusgeneralfor the whole checklist), merged by the existing summarizer, posted by a separate job that holds the write token. Same backend inputs, key discipline, pins and backstops as the reviewer.maintenance.yml: the kernel's own caller, Mondays 06:17 UTC plus manual dispatch, terra through hermes like the reviewer. Any repository copies it (docs/install.md, "a weekly maintenance digest").maintain.py: lens library, brief, digest/stub renderers,run_maintenance_scan.maintain_agent_cli/maintain_post_cli: the emit and post halves.roles.maintainer_spec: the reviewer's tools and verdict shape, tree-sized budget.GitHubClient.update_issue.result_from_datanow carries a sanitizedcategory, and the summarizer brief says to keep it, so merged findings keep their section. Reviews are unaffected (their category is empty).Why
The first digest (#332) was written by hand in an agent session. Mengye asked for a scan that is repeatable on a schedule, and one whose output nobody acts on automatically: the digest issue carries no
outerloop:stewardlabel, so intake and the steward ignore it, and research attempts never come from issues. A person turns a mechanical item into a work order when they want it done.Tests
Brief (lens focus, general covers all, unknown lens refused, syscall commands present, never blocking), digest render (sections in lens order, decisions first, permalinks with
#L, escaping and backtick balancing, counts line), stub render, the scan runner's envelopes (findings, no-verdict stub), the maintainer role shape, the poster (creates when none, rewrites only the bot's marker issue and comments, refuses review envelopes, stubs create-or-comment), both CLIs' env reading and fail-closed paths (sanitized checkout, missing tree, missing key),update_issue, and a YAML check that the write token stays out of the session jobs.Validation after merge
The reusable workflow is referenced
@main, so the first live run is a manual dispatch ofmaintenanceon this repo after merge; I will post the resulting issue link.🤖 Generated with Claude Code