Skip to content

docs(conductor): arm patrol loops with watch=work-ledger - #16036

Merged
bolichen97 merged 1 commit into
mainfrom
docs/conductor-watch-work-ledger
Oct 2, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/conductor-watch-work-ledger

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a conductor that dispatched work-ledger workers arms its patrol loop with watch="work-ledger", so quiet patrol cycles stop costing a model turn.

#12781 shipped the watch="work-ledger" field on monitor_start, but nothing an agent reads tells it to pass that field. goal-conductor's "Known limits" section still says monitor_start "gates on a single pull-request URL and nothing else today" and to wait for the field. The system prompt's monitor_start guidance only describes PR URLs. Live patrol loops on a host running current main are being armed without the field, so every one of them is a plain timer and wakes its conductor every interval.

Why it matters

A patrol loop on a timer pays one full turn per interval whether or not any worker reported, which is the cost #12781 was built to remove. The cost is only recovered when the agent arming the loop knows about the field.

Not a goal

  • No code change: the watch field, the probe and the gate are unchanged.
  • No change for conductors that do not dispatch through the work ledger (pipeline-conductor, security-conductor track their fleets in their own stores; watch="work-ledger" would observe an empty ledger for them).
  • No change to babysit or prepare-pr, which watch a single pull request.

What changed (motivation -> approach -> change)

Symptom: patrol loops armed without watch. Cause: the guidance agents copy predates #12781 and says the field does not exist. Change, docs only:

  • goal-conductor/SKILL.md Patrol section: arm the loop with watch="work-ledger", what it buys (no turn on a quiet cycle, a report pulls the next cycle forward), and to add it with monitor_update(watch="work-ledger") on a loop found without it.
  • goal-conductor/SKILL.md Known limits: drop the stale "patrol loop is on a timer" entry.
  • config/prompt.md "Using monitor_start" item 1: one sentence telling a conductor patrolling work-ledger workers to pass watch="work-ledger".

The decision this follows is already recorded in docs/request-for-change/rfc-conductor-work-ledger.md (status partial), whose Phase 3 is the watch: "work-ledger" gate on the conductor's patrol loop.

Backwards compatibility

Compatible: guidance text only; loops armed without watch keep working exactly as today.

Tests

No new tests (docs only). Ran the tests that read these two files: test/test_babysit_guidance_gates.py (the monitor_start block in prompt.md must still show a gating PR URL within its first 1200 characters), test/test_conductor_agent.py, test/test_ledger_conductor_agent.py, test/test_work_ledger_doc.py, test/test_builtin_skill_index_line.py, test/test_context.py, test/test_agent_refactor_spec_bytes.py, test/test_babysit_monitor_scenarios.py, test/metrics/test_context_blocks.py, test/test_patrol_budget.py: 373 passed, 0 failed.

Manual verification

N/A -- wording change; the field it points to is covered by #12781's tests.

Related Issues

Follows #12781.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 1, 2026 23:29
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 93b6acfee07f43d7a91fb54605920e9150c04b4a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 93b6acf

Description read

[DESCRIPTION-READ] f2206f8834eff4ca2ba03ed4016dcab1d21d34e397c2baa64412b8feb255c01b

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 93b6acfee07f43d7a91fb54605920e9150c04b4a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The conductor's own system prompt still says the watch field doesn't exist, contradicting the updated skill — the stale guidance this PR exists to fix survives at its strongest site.

Not justified as shipped

  • Item 1 — symptom-level: the PR's stated cause is "the guidance agents copy predates feat: wake a conductor from its work ledger instead of a timer #12781 and says the field does not exist", but it fixes 2 of 3 such sites. Grepped watch: "work-ledger": _CONDUCTOR_SYSTEM_PROMPT (installed as the kirocrew-conductor's prompt at src/kiro_crew/agent_materialization/conductor_agents.py:133) still says, at src/kiro_crew/agent.py:3905-3907, "(The loop is on a timer today. When monitor_start accepts a watch: "work-ledger" field, gate on that instead…)" — system-prompt text that now actively contradicts the skill, so live loops may keep arming without the field, which is the exact harm the Goal names. 1 unfixed sibling; the description never says it is left.
    Subtraction: delete that stale parenthetical from _CONDUCTOR_SYSTEM_PROMPT's Patrol section — same one-string, docs-grade edit as the two files already touched.
    Clears when: the stale sentence at src/kiro_crew/agent.py:3905-3907 is deleted (or replaced with the pass-watch instruction) on this branch.

What this change ships

Inventory (4 items) — 3 justified

Intent: make a conductor dispatching work-ledger workers arm its patrol loop with the already-shipped watch="work-ledger" gate, by updating the stale guidance agents read — a FIX (docs only).

  1. Skill's Patrol section now instructs arming with watch="work-ledger" and explains what it buys — symptom-level: same stale cause survives in _CONDUCTOR_SYSTEM_PROMPT (agent.py:3905).
  2. Skill now tells a conductor to repair an un-gated loop via monitor_update(watch="work-ledger") — justified
  3. "Known limits" entry saying the patrol loop is a plain timer removed — justified
  4. prompt.md monitor_start guidance gains one sentence telling ledger-dispatching conductors to pass watch="work-ledger" — justified

(The gate itself is on main — monitor_start/monitor_update accept watch at mcp_tools/control.py:702,855 — and the shape is covered by rfc-conductor-work-ledger.md, partial on base, whose Phase 3 is this gate on the conductor's patrol loop.)

[FIRST-PRINCIPLES-REVIEWED] 93b6acf

Description read

[DESCRIPTION-READ] 171d5e8263deb98a2f003ac68f4af85e606e57cce36cc67460cae02c67e957e5

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 93b6acfee07f43d7a91fb54605920e9150c04b4a — this comment is updated in place on each push.

Review details

Advisory only: the new watch="work-ledger" paragraph states the gate's behaviour without either of the two bounds the code enforces, and the section's renewal protocol depends on one of them.

FINDING — src/kiro_crew/builtin_skills/goal-conductor/SKILL.md:241 — a cycle where no worker reported anything costs no turn is true only 9 ticks in 10 (gate._MAX_QUIET_STREAK = 10), and the section still justifies its interval rule as "an interval longer than 10% of the runtime lets the loop expire without one cycle in the renewal window" — that rule was sized for one delivered turn per tick, so a gated patrol whose board is quiet (e.g. the human_approval item the skill tells you to wait on at interval_secs=1800) can get no delivered turn inside the last 10% of max_runtime_secs, never see a [patrol budget: …; 10% or less left] line (autonudge_service/model.py:549), and be deactivated by firing.py:140 with open items and no renewal turn → Fix: state in this paragraph that a work-ledger watch delivers only every 10th quiet cycle, so a gated patrol needs 10 × interval_secs to fit the renewal window (interval ≤ 1% of runtime), and teach scripts/patrol_budget.py check that bound.

FINDING — src/kiro_crew/builtin_skills/goal-conductor/SKILL.md:243 — The interval then only sets how often a silent fleet is re-checked, not how fast a report reaches you omits conductor_wake.ITEM_PULLS_PER_HOUR = 12: every progress write and every worker turn end spends that per-item budget, so once an item is over it _admit returns False and its next question — the status that blocks its worker on the conductor's answer — waits out the full interval_secs the paragraph has just invited you to set in hours → Fix: add that the pull-forward is capped per item per hour, so interval_secs remains the worst-case latency for a chatty item.

[OPUS-REVIEWED] 93b6acf

Verdict parsed from the review's SHA-scoped output markers for commit 93b6acfee07f43d7a91fb54605920e9150c04b4a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 93b6acfee07f43d7a91fb54605920e9150c04b4a: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 93b6acfee07f43d7a91fb54605920e9150c04b4a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 93b6acf

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 93b6acfee07f43d7a91fb54605920e9150c04b4a: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 2, 2026
goal-conductor still said monitor_start could not gate on the work ledger,
which #12781 shipped. Tell the conductor to pass watch="work-ledger" when it
arms its patrol, and add one line to the system prompt's monitor_start
guidance so any conductor that dispatched work-ledger workers does the same.
@chenmingwei23
chenmingwei23 force-pushed the docs/conductor-watch-work-ledger branch from 1dd2132 to 93b6acf Compare October 2, 2026 01:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved: PR Readiness green on this head, merges cleanly into current main, no outstanding blocking review.

@bolichen97
bolichen97 merged commit dddb57f into main Oct 2, 2026
97 checks passed
@bolichen97
bolichen97 deleted the docs/conductor-watch-work-ledger branch October 2, 2026 05:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants