Comment sweep

Catalogue row: comment_sweep · Replacement: none yet

This skill is a temporary prose interface over the recurring comment sweep.
It is the largest measured token consumer of any process in the catalogue and it
is the one with no invocable name today, which is why it is a row.

What it wraps

The recurring tracker-comment sweep. The tracker, the query that finds
unanswered comments, the identity whose replies are owed, and the directory
drafts land in are overlay content.

Overlay

Resolve the overlay with the shared resolver, the same search order every
overlay-configured skill uses:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_skill_overlay.py" comment_sweep

Order	Location	Kind
1	COMMENT_SWEEP_OVERLAY_PATH	explicit pointer — a miss is a hard stop, never a fall-through
2	each root in ONEX_SKILL_OVERLAY_ROOTS, joined with comment_sweep/overlay.yaml	discovered

It prints the resolved path, or exits non-zero naming every location it
tried. A non-zero exit is a hard stop, not a fall back to a default —
there is no default. Report its standard error and stop.

Field	What it holds
tracker_read_command	the read-only query that lists comments awaiting a reply
positive_control_command	the same query against an input known to return rows
draft_directory	where reply drafts are written
cadence	the default sweep window

Preflight, by intent

Run the preflight first at the given intent. The tracker-connectivity check is
the one that matters here: a sweep that cannot reach the tracker returns zero
rows and reads exactly like a clean inbox.

Verification contract

Replies are drafted to files, never posted, and the run is proven read-only by
a zero count of write calls — with a positive control on the read path.

Both halves are required and they fail in opposite directions:

• Read-only is proven by the absence of a write. Report the count of write
  calls made against the tracker. It is zero, and a non-zero count is a defect
  in this skill, not a finding about the tracker.
• A zero result is proven by a positive control. Run
  positive_control_command in the same pass. If it returns no rows either, the
  sweep did not work and the empty inbox is not a finding. Never suppress
  stderr on either command — an errored query and an empty one are
  indistinguishable once the error is discarded.

Reply rendering

Collect tracker facts and compute counts and identifiers deterministically. For each
reply, submit one ModelSkillRequest to the existing
onex.cmd.omniclaude.comment_sweep.v1 command topic. Its args carry:

Argument	Value
render-prompt	the rendering instruction followed by the verified fact table
work-unit-id	a stable identifier for this reply's work unit
delegation-lane	the overlay's declared lab lane
ticket	the owning ticket, when declared

The node's HandlerCommentSweepSkill renders this phase. It invokes the declared
$OMNI_HOME/omnibase_infra/scripts/onex wrapper, whose CLI environment is # local-path-ok: the handler reads OMNI_HOME literally (handler_comment_sweep_skill.py)
$ONEX_DISPATCH_VENV or $OMNI_HOME/.onex-dispatch-venv. The hooks environment and # local-path-ok: the handler reads OMNI_HOME literally (handler_comment_sweep_skill.py)
an ambient onex on PATH do not supply the CLI. No environment is rebuilt by this handler.

The handler tries onex delegate with --task-type document, an explicit lab lane,
and the declared state root. A successful render must have a fresh matching receipt
naming its endpoint and model. If the binary, wrapper, chain or receipt is unavailable,
the existing caller-injected renderer completes the reply as a fallback. The recorded
render_delegation.outcome is delegated or fallback; a fallback names its reason,
the missing command and the CLI venv searched. Preserve that record in the sweep report.

Before invoking the chain, the handler writes a work-side pending result under
$OMNI_HOME/.onex_state/comment-sweep/<correlation_id>.json, then replaces it with # local-path-ok: the handler reads OMNI_HOME literally (handler_comment_sweep_skill.py)
the delegated or fallback result. An interrupted render therefore remains visible
without a delegation receipt. The completion event
carries the record and its artifact_path; read that result's output to write the
reply draft into the overlay's draft_directory. A fallback output's RESULT: block
reports execution status and is excluded from the draft body. A failed evidence write
is a failed render, never a successful delegation. No comment is posted.

This records rendering evidence for the later routing-share readback. It does not
activate that readback or infer its denominator from delegation receipts.

Mechanical replacement

none yet. The replacement is a scheduled trigger with a firing receipt, plus
a gate that refuses to report a zero without its control attached. Both are
mechanisms; neither exists. Until they do, this row's correctness rests on the
person running it reading this section, which is exactly the failure the
catalogue records.

What this skill does NOT do

• Post, edit, resolve or react to anything on the tracker — it writes nothing
• Report an empty result without its positive control
• Discard the standard error of either command
• Name a tracker, a project, an identity or a path in this file