Repository navigation
feat(conductor): kirocrew-conductor becomes the ledger conductor - #10265
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Sound consolidation with an enforced identity alias — but the PR ratifies its own merge gate: criterion 2 waived, criterion 1 partly unevidenced. Watch
Suggestions
The shape itself is the right one: [DESIGN-REVIEWED] a6a64d7 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of All evidence gathered. Composing the review. First-Principles-Verdict: CONCERNS The swap passes its own recorded two-part merge gate by waiving criterion 2 and asserting criterion 1 on evidence with no linkable record. Not justified as shipped
What this change shipsInventory (9 items) — 8 justifiedIntent: make the work-ledger flow what the default conductor runs, keeping the old name resolving for one release — an ADDITION (a changed default), and the description matches the diff.
Watch
[FIRST-PRINCIPLES-REVIEWED] a6a64d7 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
The work-ledger flow shipped on a separate `kirocrew-ledger-conductor` spec so that migrating every existing conductor user was a decision rather than a side effect. The decision is taken: the flow ran a multi-item goal end to end (7 items across 3 rounds, each acceptance settled by `accept_eval.py` rather than by a transcript read), so `kirocrew-conductor` is what emits it. `_conductor_spec` is the one body both installers call, so the live spec and the alias cannot drift: `kirocrew-conductor` mounts `kirocrew-work`, grants `work_ledger_read` / `work_ledger_record` / `work_brief` and not `work_report`, and carries the ledger prompt. `kirocrew-ledger-conductor` emits that same spec under its old name for one release, with a description that says it is deprecated — the name is a public string a running session, a cron and a crew binding all resolve, so deleting it in the same release as the swap would break them in place. `goal-conductor/SKILL.md` is the ledger procedure and `goal-ledger-conductor/SKILL.md` is a one-paragraph pointer to it, with a byte-identical `accept_eval.py` beside each. `kirocrew-pipeline-conductor` and `kirocrew-security-conductor` still mount nothing: their children report through their own skills' scripts. `goal-conductor/scripts/ledger_entry.py` stays shipped and undocumented — deleting it and its tests is Phase 4's scope, recorded in the RFC's rollout note.
The rollout note opened "the merge criteria above are met" two paragraphs above its own record that the `watch: "work-ledger"` gate is unmerged and the timer's cost was accepted. A waiver is a legitimate decision; calling it met makes the document contradict itself and leaves a later reader unable to tell whether the wake gate is still owed. Criterion 1 now states the evidence it rests on and names the two sub-clauses that have no linkable record, rather than claiming them. The retirement spec requires a `kirocrew doctor` notice for any config still naming the alias, and none ships here: the deprecated `description` is read by an operator looking at the roster, not by a cron job or a crew binding, so without the notice the one-release window warns nobody. Recorded as a precondition for DELETING the alias and tracked as #10268. Also recorded: what a mid-goal conductor session sees when it wakes into the ledger prompt, and that `ledger_entry.py`'s deletion rides with the alias's removal rather than waiting for Phase 4 — its only remaining consumers are those sessions, which expire on the same schedule. Drops a one-entry parametrize in test_worker_agent.py for the inline filename.
777ab3b to
a6a64d7
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Maintainer review (agent-assisted), pinned to a6a64d7. Approving the owner-delegated default-conductor migration. Dedicated review verified the shared alias spec, bind-before-seed protocol and strict caller-derived ledger identity. I additionally read the previously omitted conductor test diff, pipeline-conductor spec diff and permission derivation. Tests pin the exact three-server set, verb-limited work grants, no server autoApprove, no work_report/wildcard automatic grant, and filtered KAS permissions. Pipeline/security conductor mounts remain unchanged. Alias and evaluator compatibility are retained.
Accepted nonblocking documentation issue: the promoted skill says TBD acceptance bars are not server-filtered, but the store and prompt correctly omit them; correct that carried-over paragraph. Advisory rollout evidence/waiver is accepted as disclosed, not reclassified as measured proof; alias deletion remains separately gated by #10268. Source/test review and current-head CI; no local suites rerun.
…odotdev#10265) * feat(conductor): kirocrew-conductor becomes the ledger conductor The work-ledger flow shipped on a separate `kirocrew-ledger-conductor` spec so that migrating every existing conductor user was a decision rather than a side effect. The decision is taken: the flow ran a multi-item goal end to end (7 items across 3 rounds, each acceptance settled by `accept_eval.py` rather than by a transcript read), so `kirocrew-conductor` is what emits it. `_conductor_spec` is the one body both installers call, so the live spec and the alias cannot drift: `kirocrew-conductor` mounts `kirocrew-work`, grants `work_ledger_read` / `work_ledger_record` / `work_brief` and not `work_report`, and carries the ledger prompt. `kirocrew-ledger-conductor` emits that same spec under its old name for one release, with a description that says it is deprecated — the name is a public string a running session, a cron and a crew binding all resolve, so deleting it in the same release as the swap would break them in place. `goal-conductor/SKILL.md` is the ledger procedure and `goal-ledger-conductor/SKILL.md` is a one-paragraph pointer to it, with a byte-identical `accept_eval.py` beside each. `kirocrew-pipeline-conductor` and `kirocrew-security-conductor` still mount nothing: their children report through their own skills' scripts. `goal-conductor/scripts/ledger_entry.py` stays shipped and undocumented — deleting it and its tests is Phase 4's scope, recorded in the RFC's rollout note. * docs(rfc): criterion 2 is waived, not met, and the doctor notice is owed The rollout note opened "the merge criteria above are met" two paragraphs above its own record that the `watch: "work-ledger"` gate is unmerged and the timer's cost was accepted. A waiver is a legitimate decision; calling it met makes the document contradict itself and leaves a later reader unable to tell whether the wake gate is still owed. Criterion 1 now states the evidence it rests on and names the two sub-clauses that have no linkable record, rather than claiming them. The retirement spec requires a `kirocrew doctor` notice for any config still naming the alias, and none ships here: the deprecated `description` is read by an operator looking at the roster, not by a cron job or a crew binding, so without the notice the one-release window warns nobody. Recorded as a precondition for DELETING the alias and tracked as kirodotdev#10268. Also recorded: what a mid-goal conductor session sees when it wakes into the ledger prompt, and that `ledger_entry.py`'s deletion rides with the alias's removal rather than waiting for Phase 4 — its only remaining consumers are those sessions, which expire on the same schedule. Drops a one-entry parametrize in test_worker_agent.py for the inline filename. --------- Co-authored-by: Joe Guo <zejiangg@amazon.com>
Problem / Motivation
The work-ledger conducting flow ships on a spec nobody reaches by default.
kirocrew-conductor— the agent a user actually gets when they hand over a long-horizon goal — still learns each worker's state by reading its transcript against a stored cursor, and still squeezes item state intosession_ledgerartifactsvalues under a 2000-character-per-entry cap. The ledger flow, with one record per item and an evaluator verdict instead of a transcript read, lives onkirocrew-ledger-conductor, which a user has to know to name.That split was deliberate (#9277, Phase 2.5): mounting the tools on the shipped conductor would have moved every existing conductor user onto a different procedure without asking. The RFC set two merge criteria for closing it, and this PR is that close.
Why it matters
Every conductor goal that runs on the default spec pays the old costs — a per-item transcript read per patrol cycle, item state in a capped string field, and a
donethat is settled by the conductor's own reading rather than byaccept_eval.py. Leaving the flow behind a name means the improvement exists and nobody gets it, and it meansgoal-conductor/SKILL.mdstays frozen against every later ledger phase.What changed (motivation → approach → change)
Goal: make the ledger flow the default without breaking the old name.
Approach: one spec body, two filenames. Two installers that each hand-build the same list are exactly where a grant lands on one spec and not the other, and an alias that emits a different spec silently changes what an in-flight session can do — which is the one failure the alias exists to prevent. So
_conductor_spec(name=, description=, filename=, source=)is the single body;filenameandsourceare the only per-installer values and neither reaches the emitted JSON (filenameis the KASagent_idin the derive's log line,sourcenames the installer in the withheld-grant audit event).What that produced:
kirocrew-conductormountskirocrew-work, auto-approveswork_ledger_read/work_ledger_record/work_briefand notwork_report, and carries the ledger prompt. Every property the old installer's docstring argued for is unchanged: no file-writing tool at all (notfs_write, notcode),@kirocrew-core/@kirocrew-dashboard/@kirocrew-workmounted whole but auto-approved verb by verb,execute_bashmounted and never auto-approved,permissionsderived from the FILTERED grant list.kirocrew-ledger-conductoremits that same spec under its old name for one release, withdescriptionprefixedDeprecated alias of kirocrew-conductor (removed next release).The name is a public string — what a running session records as its agent, what a seed prompt names for a second-level conductor, what an operator typed into a cron — so deleting it in the same release as the swap would break those in place._CONDUCTOR_SYSTEM_PROMPT; its opening no longer says "you differ fromkirocrew-conductorin ONE thing" but states the ledger flow directly, and the dispatch table's decomposable row nameskirocrew-conductor._LEDGER_CONDUCTOR_SYSTEM_PROMPTis gone rather than duplicated.goal-conductor/SKILL.mdis the ledger procedure (the content ofgoal-ledger-conductor/SKILL.md, references renamed);goal-ledger-conductor/SKILL.mdis a one-paragraph deprecation pointer to it. Both keep a byte-identicalscripts/accept_eval.py, so a session that already loaded the old skill name keeps a working evaluator. The builtin-skill scope gate passes on the moved content.kirocrew-pipeline-conductorandkirocrew-security-conductorstill mount nothing. Their children report through their own skills' scripts, so the mount would grant a flow whose procedure neither runs.goal-conductor/scripts/ledger_entry.pyis still shipped, now unreferenced by the SKILL.md. Deleting it andtest_conductor_ledger_entry.pyis Phase 4's scope in the RFC, and the rollout note says so rather than leaving the reader to notice.Docs updated to match:
src/kiro_crew/docs/agents.md,docs/feature-map/README.md,docs/system-specs/modules/pipeline-conductor.md,docs/request-for-change/README.md, and the RFC — which gains a2.6 — the swapphase row and a Rollout note — swap done section recording the decision against its own criteria, marks Phase 2.5's superseded exit criteria as superseded, and re-frames §Motivation as the historical cost it now is.After the change,
grep -rn kirocrew-ledger-conductor src test docs website/src scriptshits only the alias installer, the alias filename constant, deprecation text, and the RFC's history.Tests
test_ledger_conductor_agent.pyis now the alias's identity proof.test_the_alias_spec_is_identical_apart_from_name_and_descriptioninstalls both specs under one stub and compares the emitted JSON field by field —{k for k, v in live.items() if alias.get(k) != v} == {"name", "description"}— rather than asserting both call the same helper, because a helper is what a later edit routes around. It also pins that the deprecation prefix is present and that the charter sentence survives it.test_the_governance_ceiling_reaches_the_alias_the_same_waypins that a ceiling strips the same ref from both, onallowedToolsand on the derived KAS block.test_the_work_mount_lands_on_all_four_surfacesassertstools,mcpServers,allowedToolsandpermissions.rules[].match. The last is the one that silently survives an incomplete edit: a spec can look correctly mounted on kiro-cli while the KAS projection grants nothing, and every patrol cycle then stalls on an approval nobody is there to give.work_reportandkirocrew-work/*are asserted absent on both grant surfaces.test_prompt_carries_no_work_ledger_procedure→test_prompt_carries_the_work_ledger_procedure(and it pins dispatch ORDER, not just presence);test_mcp_surface_is_narrowed_to_core_plus_dashboard→..._plus_workas an exact set; the two exact-allowedToolslists and the KASmatchexpectations gain the three work resources.test_worker_agent.py's "a shipped conductor does not mount the server" keepskirocrew-pipeline-conductorand parametrizes the positive case over the live spec and the alias.watch: "work-ledger", skill-body and quoted-heredoc pins moved totest_conductor_agent.pyagainstgoal-conductor/SKILL.md. The codec doc-ratchet is replaced by one asserting the skill routes item state to the store and names no codec.test_builtin_skill_index_line.py's parametrize list moves togoal-conductor, and a new test pins that the deprecated skill's rendered index line says "Deprecated" and namesgoal-conductor— that one line is all an agent reads before deciding whether to load a skill.test_the_evaluator_is_byte_identical_to_the_shipped_oneis unchanged and green.Run locally with the repo venv: 918 passed across
test_conductor_agent.py,test_ledger_conductor_agent.py,test_worker_agent.py,test_pipeline_conductor_agent.py,test_security_conductor_agent.py,test_builtin_skill_index_line.py,test_work_ledger.py,test_work_ledger_tools.py,test_conductor_ledger_entry.py,test_agent.py,test_agents_roster_contract.py,test_agent_discovery.py,test_skill_listing_cost.py,test_agent_template_skills.py; a further 317 across the installer/permission/roster consumers (test_derived_agent_permissions_consumers.py,test_kas_agents.py,test_acp_set_mode_all_agents.py,test_agents_janitor.py,test_migrate_agent_specs.py,test_agent_sdk_boundary.py,test_spawn_agent_roster.py,test_agent_roster_shared.py,test_pipeline_conductor_skill_contract.py,test_agent_import_hoist.py,test_agent_lifecycle_cycle.py).Gates run with their own base-ref exports:
black --target-version py310 --check,isort --check-only,flake8,mypy src/kiro_crew/agent.py,check_brand_name.py,check_comment_history.py,check_focus_cue.py,check_changelog_history.py,check_harness_parity.py,check_feature_map.py,check_builtin_skill_scope.py,docs_lint.py— all clean.Manual verification
N/A — the whole change is the content of two generated JSON specs and two markdown files, and the installer tests read back the JSON that was actually written.
Related Issues
Implements the merge criteria in
docs/request-for-change/rfc-conductor-work-ledger.md§Rollout note (v2.1), following #9277.Deprecation plan
kirocrew-conductorkirocrew-ledger-conductorgoal-conductorgoal-ledger-conductoraccept_eval.pyNothing new should name either deprecated item. A session, cron or crew binding that already names the old agent keeps resolving through this release and gets the merged spec, not a
Mode not foundfailure. Phase 4 removes both names and deletesgoal-conductor/scripts/ledger_entry.pywith its tests.Review round 2 — what the advisory lanes changed
Design Review and First Principles both returned 🟡 CONCERNS on the same real defect, and both are addressed in commit 2:
watch: "work-ledger"gate is unmerged. It now says criterion 1 met / criterion 2 waived, with the re-judgement stated: the objection criterion 2 encoded was "not yet cheaper than the agent it would replace", and the agent actually being replaced pays a per-item transcript read per cycle, which is not cheaper than onework_ledger_read.blocked/question, a second-level conductor) that have no linkable record rather than claiming them.kirocrew doctornotice the retirement spec requires does not ship here, and that gap is real: the deprecateddescriptionis read by an operator looking at the roster, not by a cron job or a crew binding, so without a notice the one-release window warns nobody. Recorded as a precondition for deleting the alias (not for the swap — an unmigrated config keeps working while the alias exists) and tracked as kirocrew doctor should flag a config naming a deprecated agent spec #10268.session_ledgerartifacts; every old tool is still mounted so it can finish its round, and what it must not do is keep both records.ledger_entry.py's deletion moves out of Phase 4 and rides with the alias's removal next release, per the FP lane's subtraction: its only remaining consumers are those mid-goal sessions, which expire on the same schedule as the alias. Phase 4 keeps the Crew page surfaces.@pytest.mark.parametrizeintest_worker_agent.pyfor the inline filename.Round 3
Design Review's one actionable suggestion applied: the RFC's rollout note said "Both are removed next release" unconditionally while the same note makes #10268's doctor notice a precondition for that deletion. The note now gates the removal on it explicitly, so the removal PR inherits the gate from the document it will be read against.
Both lanes' remaining Watch items are maintainer decisions rather than changes to make here, and both name that in their own
Clears when:lines:blocked/questionitem, a second-level conductor). Clearing this is "a maintainer explicitly accepts the note's evidence."work_ledger_read, and does not present a measurement. Clearing this is Phase 3's wake gate merging, or a maintainer ratifying the waiver.Both are advisory; neither lane blocks readiness, and the First Principles inventory is 9 items / 9 justified after round 2.
Checklist