Skip to content

docs(goal-conductor): dissolve Known limits, fix stale approval list, never block a wake on an ask - #37618

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
docs/goal-conductor-known-limits-dissolved
Nov 15, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
docs/goal-conductor-known-limits-dissolved

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The goal-conductor skill has no "Known limits of this version" section; each of its bullets sits where it applies, and the text the conductor reads matches what the code does.

The owner asked why the skill carries a "Known limits of this version" section. It is a 96-line grab bag at the end of goal-conductor/SKILL.md: real limits, tool-loading tips, rules that belong in a step, and duplicates. Part of it is stale. It says session_send / session_close need an approval per seed, answer and close, but the code auto-approves both into a conductor's own child. The Needs-human checklist lists four risky cases that differ from the five asks in Patrol step 2. references/worker-debate.md sizes a debate budget from a goal item cap that no longer exists. Three passages contradict another passage in the same file.

Why it matters

The conductor plans around the text. A stale approval list makes it expect clicks that never come (and budget turns for them). A second, different ask list lets it ask for a case the five asks say to decide, or skip one they say to ask. A budget tied to a removed cap has no value.

Not a goal

  • Moving Remote dispatch behind its preview (separate PR).
  • The automation / Round-0 go-ahead change and the non-blocking ask form (separate RFC).
  • De-duplicating the rest of the skill or moving rare paths to references (later PRs).
  • Covered by feat(prompts): one reroute-first ask policy for every crew kind #37609, left as on main here so the two do not conflict: W5 (escalate only ask cases), W6 (refused / error no longer "ask"), W8 (third empty round: the conductor decides, records and reports, no ask; the round count is its own bound, not an ask case), W10 and W11 (worker-debate.md rules 4-5: a self-set cap or budget is the conductor's call, an owner-approved spend stays (b)).
  • The Needs-human checklist's four risky cases vs the five asks, in the skill and in agent_parts/spec_prompts.py:438-442: covered by feat(prompts): one reroute-first ask policy for every crew kind #37609, which points both at ask cases (a)-(e). This PR leaves that text as on main.

What changed (motivation → approach → change)

Audit of the section → every bullet placed by kind (real limit stays short where it applies; tool tip becomes one line; misplaced rule goes into its step; duplicate is deleted) → heading removed. Every stale claim was checked on origin/main fd4c0d3 first. The intro gains a "What prompts." paragraph that matches the grant code; the debate budget gets a number; three contradictions are reworded. Owner ruling 2026-11-15 added two ask fixes from the audit: an unassertable item becomes a file item (W4), and a human_approval ask in a turn nobody typed is recorded with work_ask_record / needs_you instead of a blocking ask_question (W7). Code citations, the per-bullet placement and every moved safety line are under "Evidence" below.

Evidence (stale claims, placement, safety lines)

fix old text code new text
approvals (stale per-seed/answer/close prompt claim) "session_send and session_stop are deliberately NOT auto-approved … one approval per item at dispatch, per question, per close"; list omits work_ask_record, work_report dashboard/chat_turn/tool_approval.py:353-354,447-464 own-child send/close auto-approved for kirocrew-conductor/kirocrew-team-lead; config/sections_agent.py:1452-1453 default True; agent_parts/spec_grants.py:207-209 work_dispatch withheld; :268-272, :483-489, :501-521 granted lists intro "What prompts." paragraph
checklist ask cases step 1 lists four risky cases — covered by #37609 (not changed here)
T3 debate budget "work items, default half the goal's item cap" #33601 removed the cap (DEFAULT_GOAL_ITEM_CAP = 20); work_ledger_writes.py:506 caps open items only "work items, default 10" (the same number as before)
C1 "workers … do not publish that page" vs "an authorized descendant publishes it" — workers never publish your board page; one authorized descendant may publish task-dashboard
C2 "just do the work in this session" intro: this spec has no file-writing tool dispatch the one item or hand the goal back
C3 "separate calls only to bind an existing session", then a list whose step 2 creates one validation_parts/messaging_session_schemas.py:614-633 work_dispatch always creates separate calls without work_dispatch, or to re-bind (skip step 2)
W4 "not assertable: say so and treat it as a needs-human item" file is an evaluator kind (scripts/accept_eval.py) make it a file item; human_approval only when a person must judge it
W7 human_approval always verified by a blocking ask_question (up to 30 min) patrol wakes open with [auto-nudge cycle N] (autonudge_service/model.py:884) or [work-ledger wake] (probes/work_ledger.py:109-334); work_ask_record is granted (agent_parts/spec_grants.py:485) in a turn nobody typed: work_ask_record + needs_you / [OPTIONS:], keep patrolling; ask_question only in a user-typed turn
W8 — — covered by #37609 (not changed here)

Known-limits bullets, old → new:

bullet to
ask_question holds the turn clause in step 3 human_approval paragraph ("keep patrol work out of the turn that asks", the wording #37609 keeps)
deferred tools / tool_search ids one intro line
not_bound for a root conductor deleted; same rule in "When a conductor dispatched you"
answering uses session_send; prompt is not an ask intro "What prompts"
cron may drive its own sessions one clause by work_dispatch failures
never dispatch a writing item onto a conductor deleted; same rule in "Which agent"
MCP mount is the grant; session_control_disabled lines by work_dispatch failures
auto-approved list intro "What prompts" (T2)
session_send reports delivery dispatch step 4
summary is prose step 3 reported clause
orphaned items keep writes step 1 flag paragraph
out-of-bounds session targets "Which agent"
shell only for the evaluator; fixed argv intro, next to the execute_bash fallback

Safety lines moved (old line on fd4c0d3 → new section): S2/S3 evaluator takes no command, fixed argv, refused never routed around (1146-1158 → intro; step 3 refused line unchanged); S11 never route an item to task_run/workflow_run/spawn_* (1111-1113 → intro "What prompts"); S32 decide from verdict, not summary (1131-1136 → step 3); S38 out-of-bounds targets refused (1142-1145 → Which agent); S39 sends to sessions you did not create prompt, you ingest external content (1114-1121 → intro "What prompts"); S16 conductor specs cannot write (1091-1095 → kept at "Which agent"); ask_question blocks (1064 → step 3).

Backwards compatibility

Compatible: skill text only; no code, schema or config changes.

Removes nothing: every bullet of the removed section is kept at a new place or already said elsewhere in the same file (tables above).

Tests

  • test/test_conductor_agent.py::test_skill_states_the_real_approval_cost now pins the true approval text: own-child send/close do not prompt, other sends prompt, work_dispatch prompts once per item, session_stop and other core tools prompt.
  • test/test_conductor_agent.py::test_skill_never_blocks_a_wake_on_a_question_card pins W7 (no ask_question in a turn nobody typed) and W4 (unassertable -> file item).
  • Ran every test/test_*.py that reads the goal-conductor skill (25 files): 860 passed.

Proof: not provable -- docs or config only

Manual verification

N/A — skill text only; the pinned tests read the shipped file.

Related Issues

N/A

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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 15, 2026 13:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 8ae1ccf6ecb93444c6a722bae02618fe16a702af 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 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Only the skill text and its pins change, and it all reverts cleanly; the new approval wording matches tool_approval.py.

Notes

  • The paragraph "What prompts." says session_send/session_close into a session the agent created do not prompt. That is false for the deprecated kirocrew-ledger-conductor alias. It loads this same skill through _conductor_spec, but _CONDUCTOR_OWN_CHILD_AGENTS (tool_approval.py:354) holds only kirocrew-conductor and kirocrew-team-lead. The old text said the same thing, so this PR does not make it worse.

[DESIGN-REVIEWED] 8ae1ccf

Description read

[DESCRIPTION-READ] 604e0a619f140a1e4cd44e6a2bb5ccb4eb5f5d5780ab3afe8dbf04e2f4f9a3c5

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 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 8ae1ccf6ecb93444c6a722bae02618fe16a702af — 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 does not.

First-Principles-Verdict: PASS

W7 changes how the conductor behaves on every patrol wake, not just its text. Its only recorded support is an owner ruling quoted in the description, and it sits close to the "non-blocking ask form" that ## Not a goal defers to an RFC.

Notes

  • Item 6 — inherited: "Owner ruling 2026-11-15 added two ask fixes", while ## Not a goal says "the non-blocking ask form (separate RFC)". The new branch ("In a turn nobody typed … never call ask_question: record the ask with work_ask_record") reuses the Patrol step 2 work_ask_record/[OPTIONS:] form, so I can't read it as a new shape without making a judgement call. That keeps it a note rather than trigger (c). Subtraction: drop the nobody-typed branch from the human_approval paragraph and defer it to the RFC that ## Not a goal names.

What this change ships

Inventory (8 items) — 6 justified

Intent: make the goal-conductor skill text match what the code does by spreading its "Known limits" section across the steps it belongs to. This is a FIX.

  1. The "Known limits of this version" section is gone; each bullet now sits in the step it applies to — justified
  2. The approval list now says own-child send/close don't prompt and lists work_ask_record/work_report — justified
  3. The deferred-tool tool_search tip is now one line in the intro — justified
  4. The evaluator's fixed-argv safety text moved to the intro, next to the execute_bash fallback — justified
  5. An unassertable item becomes a file item instead of a needs-human item — rides along, an owner-ruled behaviour change
  6. On a wake nobody typed, a human_approval ask is recorded instead of blocking on ask_question — rides along, an owner-ruled default change
  7. The debate budget is "default 10" instead of half a removed cap — justified
  8. Three self-contradicting passages reworded (board publishing, a small goal, separate dispatch calls) — justified

[FIRST-PRINCIPLES-REVIEWED] 8ae1ccf

Description read

[DESCRIPTION-READ] 7036739842f3d92ef89904dcdb358598d660d033c28994ea610a1b9c84af54a7

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 8ae1ccf

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

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8ae1ccf

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

@iamwhatever iamwhatever changed the title docs(goal-conductor): dissolve Known limits, fix stale approval list and ask cases docs(goal-conductor): dissolve Known limits, fix stale approval list and contradictions Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the docs/goal-conductor-known-limits-dissolved branch from 72bf066 to 2aefa07 Compare November 15, 2026 13:55
@iamwhatever iamwhatever changed the title docs(goal-conductor): dissolve Known limits, fix stale approval list and contradictions docs(goal-conductor): dissolve Known limits, fix stale approval list, never block a wake on an ask Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the docs/goal-conductor-known-limits-dissolved branch 2 times, most recently from fa3b7d7 to 55aef1f Compare November 15, 2026 14:02
@iamwhatever
iamwhatever force-pushed the docs/goal-conductor-known-limits-dissolved branch from 55aef1f to 8ae1ccf Compare November 15, 2026 14:05
@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 15, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 15, 2026 15:24

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed head 8ae1ccf. These checks were made on that head:

  • The new "What prompts." list matches the three grant tuples in agent_parts/spec_grants.py and the own-child send/close verbs in tool_approval.py.
  • work_dispatch is still withheld.
  • The three wake markers W7 names all exist in the code.
  • work_ask_record accepts a done human_approval item.
  • The debate budget default of 10 replaces a cap that no longer exists.
  • Each sampled Known-limits bullet is still present at its new place.
  • The new and changed test assertions hold against the head file.

Done well: each stale claim is fixed against the grant code, and the body has a per-bullet table showing where every removed line went.

The design is signed off under the standing maintainer sign-off for changes by team members.

Optional:

  • W4 (SKILL.md:111) is circular, because file is already one of the listed kinds. A file bar also passes once the report exists. Consider saying that the conductor reads the report before it closes the item accepted.
  • W7 (SKILL.md:645) lists three "turn nobody typed" markers. #37609 lists nine, including [monitor wake]. Consider pointing at one shared list and naming the merge order with #37609.
  • test_skill_states_the_real_approval_cost compares prose with prose. Asserting the backticked verbs equal _CONDUCTOR_CORE_GRANTS and _CONDUCTOR_OWN_CHILD_VERBS would catch the next drift.

@KiroCrewCaptain
KiroCrewCaptain merged commit b1e65d2 into main Nov 15, 2026
99 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the docs/goal-conductor-known-limits-dissolved branch November 15, 2026 15:25
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 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