Skip to content

docs(rfc): wake a conductor when a waiting worker's wake_at comes due - #28896

Merged
kyleseaman merged 1 commit into
mainfrom
docs/rfc-work-report-wake-at
Nov 3, 2026
Merged

kyleseaman merged 1 commit into
mainfrom
docs/rfc-work-report-wake-at

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the owner's decision to let a waiting worker say when it should be resumed, so the conductor is woken at that time instead of hours later.

A worker that waits on a time (for example a GitHub rate-limit reset) reports progress, which never wakes the conductor. The one stall wake per report comes 15 minutes after the report, usually before the wait is over. After that the ledger reads idle and the patrol waits 40 quiet ticks, about 6.7 hours at the 600 s interval. On 2026-11-02 this left a worker idle that long. Workers must not use wait, because it holds a turn on the shared kirocrew-core pool.

A research pass over main (re-checked at 41bade9256) found:

  • progress is left out of WORK_WAKE_STATUSES on purpose (src/kiro_crew/work_vocab.py). is_actionable_event in src/kiro_crew/ledger_wake.py refuses it on its status alone.
  • The stall wake in src/kiro_crew/probes/work_ledger.py spends the token stall:<last_report_at>. A spent token never fires again while the item is open.
  • PATROL_MESSAGE in src/kiro_crew/conductor_patrol.py says "Ignore progress", and the goal-conductor skill maps progress to "nothing".
  • _IDLE_LEDGER_QUIET_FLOOR (40 ticks) in src/kiro_crew/autonudge_service/gate.py sets the 6.7-hour gap.
  • The gap has existed since the work-ledger wake first shipped (feat: wake a conductor from its work ledger instead of a timer #12781). It is not a regression. fix(autonudge): skip a work-ledger quiet-floor turn when the ledger has not moved #18112 made the floor four times longer to save cost.

Why it matters

A conductor running several workers loses hours of progress every time one waits on a rate limit or a CI run. The work sits finished-but-parked until a person notices or the floor turn comes. The new field changes the worker contract and a crew-log entry, so GOVERNANCE.md asks for an RFC on main before the code.

Not a goal

  • No code. The implementation follows in its own pull request after this merges.
  • Event waits (CI finished, PR merged). Polling GitHub from the gateway spends the same rate-limit budget that caused the wait; the worker picks a recheck time instead.
  • Changing which statuses wake the conductor, the stall token, or the idle floor.

What changed (motivation → approach → change)

  • Adds docs/request-for-change/rfc-work-report-wake-at.md, status accepted (the repository owner chose this design on 2026-11-03).
  • Adds its row to the index in docs/request-for-change/README.md.

The design: an optional wake_at (ISO-8601 UTC) on a progress work_report, refused if in the past or more than 24 h ahead. It is stored on the ledger item and the crew-log entry, and shown in work_ledger_read (compact too) and on the goal board. Each tick the work-ledger probe compares one timestamp, with no network call and no model turn. When the time comes it raises one wait_due wake, deduped per (last_report_at, wake_at). An item is not flagged stale before its wake_at. The patrol text, goal-conductor skill and worker prompt change to match.

Alternatives in section 6: a worker-armed one-shot monitor_start (the wait stays invisible on the board and fails silently when the worker forgets), and re-waking the conductor on stale (a model turn per re-wake, and it undoes #18112's saving). Section 7 estimates about 80 to 120 non-test lines and lists the files.

Backwards compatibility

Compatible: docs only; nothing that works today changes.

Removes nothing: the diff only adds a document and an index row.

Tests

Proof: not provable -- docs or config only

scripts/docs-lint.sh passes locally.

Manual verification

N/A — docs only; every file and symbol the RFC cites was re-checked on main 41bade9256.

Related Issues

Follow-up implementation PR will reference this one.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

Adds rfc-work-report-wake-at.md (status accepted, repository owner's decision 2026-11-03) and its index row. A progress work_report may carry an optional wake_at (ISO-8601 UTC, at most 24h ahead). The work-ledger probe raises one wait_due wake when it passes, with a timestamp compare and no network call, and the item is not stale before it.

Docs only; the implementation follows in its own pull request.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 3, 2026 06:12
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d764cdca71e99cf727edca5dfc48e0e4e5f233f1 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision d764cdca71e99cf727edca5dfc48e0e4e5f233f1 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d764cdca71e99cf727edca5dfc48e0e4e5f233f1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this PR only adds documentation, and the RFC covers the root cause (no time field, plus a stall token that fires only once) with a timestamp check that never calls the network.

Notes

  • The "waiting until HH:MM" row on the goal board (§3.2) is a visible UI change, so the implementation PR will need a screenshot of it.
  • §3.4 lets a worker that crashed mid-wait go unflagged for up to 24 h. The wait_due wake still catches it, so there is no change to make. Note that trade-off in src/kiro_crew/docs/work-ledger.md when it ships.

[DESIGN-REVIEWED] d764cdc

Description read

[DESCRIPTION-READ] ef00bf6068c8ebe01c0ced9924e73580eef5a09a103010ffcdbf78a0122f0abf

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 Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d764cdca71e99cf727edca5dfc48e0e4e5f233f1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d764cdc

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d764cdca71e99cf727edca5dfc48e0e4e5f233f1 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d764cdc

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable d764cdca71e99cf727edca5dfc48e0e4e5f233f1 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 3, 2026
@kyleseaman
kyleseaman merged commit ce40057 into main Nov 3, 2026
104 of 105 checks passed
@kyleseaman
kyleseaman deleted the docs/rfc-work-report-wake-at branch November 3, 2026 16:25
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 3, 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