Repository navigation
feat(team-lead): team-management rules decided by mechanisms that already exist - #18856
chenmingwei23 wants to merge 3 commits into
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, fix the RFC index row: it says [DESIGN-REVIEWED] 099ca65 Description read[DESCRIPTION-READ] 9ca324491b2b063b33a11870f5d6df8743c4986afbae93723e6681b24cd2dd3f 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 |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Queuing on Not justified as shipped
What this change shipsInventory (7 items) — 5 justifiedIntent: give the team lead a rule for each team-level call, naming the mechanism that already decides it. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 099ca65 Description read[DESCRIPTION-READ] d33292b1b68bd985bee1c451b7d49018eabad3c5034873fb3a8dfe8f1c26d5a5 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings that block the merge. FINDING — src/kiro_crew/builtin_skills/team-lead/SKILL.md:188 — the skill tells the lead to send a tracker that "reads every ledger and the pull requests, writes one summary item -- and the [OPUS-REVIEWED] 099ca65 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 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: |
ef9fa56 to
61bfef0
Compare
61bfef0 to
d9e33f4
Compare
|
This PR gives the team-lead crewmate rules for running a team: an |
Every agent shipped for running work is either a leader that cannot write a file or a worker that cannot create a session. A conductor spec withholds fs_write and code deliberately, which is what makes "never does a work item's work itself" true against its tool list; the worker keeps the writers and mounts nothing that can dispatch. So a one-line fix on a critical path costs a whole dispatch, or a six-item goal runs in series in one session with no board and no evaluator. kirocrew-team-lead is the union. Its installer never overwrites the template's tool list, so the writers and shell arrive from the template and the dispatch servers are appended; every auto-approve is an existing grant tuple reused verbatim, with the bare whole-server entry subtracted so the per-verb list is a real narrowing rather than a wildcard with names beside it. work_report stays withheld: it writes into a parent's record, and this crewmate is the root of its own goal. The product ships the template and creates no crewmate. The dashboard verbs resolve their crew from the session and answer only in a crewmate thread, and the server behind them is opt_in with no spec permitted to emit it, so the record is what completes the agent -- and binding one is the operator's own `kirocrew agent create --kiro-agent kirocrew-team-lead`, which the RFC and the skill document. The installer attributes the file BEFORE it validates grant shape, and only an ABSENT path is written into. A file of this name that declares another name, does not mount both servers this agent leads through, does not parse, or cannot be read deterministically is left untouched and the install declined at ERROR: no backup is written and the agent stays unselectable under that name until the operator removes or renames it. That is the dashboard-author contract rather than the derived worker's overwrite, and the difference is the remedy -- the worker spec is re-checked before every dispatch and has no operator path out, while this one is optional and selected by name. A read that may succeed later holds for one rebuild instead, so no file is judged on one bad read. The team-lead builtin skill is a delta over goal-conductor: the echo, the intake hook, the do-it-yourself test, the nested-conductor default and the dashboard, with dispatch, patrol, acceptance, stop conditions, durable state and capacity pointed at rather than restated.
463bfbc to
5e05a42
Compare
d9e33f4 to
8cedd7c
Compare
1. reset_agent_model swallowed every exception from the ownership predicate into False. A transient read of the ownership record was therefore treated as "not our write", so the reset rewrote the spec without renewing its recorded digest and every later start refused it, with no heal path for this stem. Distinguish "answered: not ours" (stay False) from "could not read ownership" (the strict readers' transient classes): the latter propagates so the reset aborts before mutating the file. 2. The team-lead KAS payload is built from the on-disk spec before the admission gate's unbounded queue wait. A governance refresh during the wait rebuilds the disk spec (stripping any grant the tightened ceiling removes), but the already-built payload still carries the old grants and is what session/new registers. The disk re-read at admission cannot see this. Record the governance generation the payload was built under and recheck it at admission and at activation (create and resume); a mismatch refuses the start so it is rebuilt against the live ceiling. The team-lead stem mirrors no default and so had no DerivedSpecSnapshot bracketing its consume window; this is the owned-stem companion to that check. 3. On the native kiro-cli path the team lead was consumed inside no bracket at all. Both guards answered None there for different reasons: require_fresh_derived_spec by its scope guard, because the team lead mirrors no default, and the generation recheck because that path builds no KAS payload and so recorded nothing. Two "not applicable"s are not "verified", and None was conflating "not our agent" with "our agent, nothing recorded" -- the second is an unanswered question, which may not be admitted. The bracket now records the governance answer itself before the read that fixes the consumed bytes (the skill projection, or kiro-cli's own disk read at set_mode) and rechecks it after the activation returns, terminating the session on a mismatch. stale_payload_generation_reason takes the agent as a required argument so the two None cases are decided rather than collapsed, and the admission site asks only where a payload exists, so a native start is not refused for a question not yet due. 4. The dashboard model PATCH recorded model_managed BEFORE confirming ownership. That confirmation propagates a transient ownership-read failure by contract, so the raise arrived with the sidecar already claiming the pin and with nothing written to the file -- a half-applied state whose spec reproduces no recorded digest, so every later start refuses it and the next rebuild carries a pin the bytes never received. Settle ownership first and reuse the one result for the digest renewal, so that failure aborts with nothing written and the decision and the renewal cannot disagree. Adds regression tests for all four, including the over-tight controls: an unchanged generation admits a native start, a governance move leaves a non-team-lead start alone, and the admission site stays quiet on a host with no payload.
5e05a42 to
961546e
Compare
The team-lead crewmate had rules for running a work ITEM and none for running a TEAM, so the calls a lead makes between items -- how big a wave may be, what stops a third conducting level, whether two lines merge, when the board outgrows one patrol read, and who may write a shared file -- were decided from feel while a mechanism in the tree could have decided each one. The skill gains a section naming those mechanisms: resource_status and its four posture words with the server's own session ceilings, MAX_DEPTH as what refuses a third level, close-and-reseed as the merge, the concrete trigger for a tracker worker, and single ownership per shared file and per output. The charter adds only what it does not already carry. Its capacity section gains one sentence -- a posture of unknown means the reading failed, so it takes the same lighter path as tight -- and its new section covers the three calls it had no text for. The one-level nesting instruction is not restated, because both surfaces already carry it and a procedure stated twice drifts until a reader follows neither copy. Tests pin each rule to its mechanism on the surface that carries it, assert the absence of a duplicate instruction, and run a positive control first so an empty read cannot pass. An RFC one-pager records the decision.
8cedd7c to
099ca65
Compare
961546e to
c2ecacf
Compare
966c7da to
f09b12e
Compare
Problem / Motivation
Goal: A team lead that decides how to run its team from the mechanisms already in the tree, instead of from feel.
The shipped
kirocrew-team-leadcrewmate knows how to run a work ITEM andalmost nothing about running a TEAM. Its skill and charter cover the
do-it-yourself test, the dispatch order, the patrol cycle and the board, so
every rule it carries is about one item at a time. The questions a lead hits
between items have no answer anywhere in the tree:
that the rule rather than a number I could ask to have raised?
Every one of them has a mechanism that could decide it, and three of those
mechanisms will REFUSE the lead rather than negotiate: the ledger's depth cap,
the server's per-creator session ceiling, and the approval gate on
session_adopt. With no rule naming them, the lead guesses.Why it matters
The failures are not slow, they are silent, and each one reads as ordinary
progress on the board.
A lead that dispatches a wave without reading capacity gets refusals partway
through it, so half a wave runs and the other half looks like a slow start. The
same lead whose capacity probe FAILS has no rule at all today: the reading
comes back
unknownand the decision falls back to feel at exactly the momentthere is no information to make it with. Two lines left unmerged keep handing
work back and forth, and the handoffs cost rounds that never show up as a red.
A fleet grown past one patrol read loses items quietly, because a truncated
read looks exactly like a short one. Two children writing one file clobber each
other, and an author grading its own work reports the result it already
believes.
All of them land on the owner as a goal taking longer than it should, with
nothing on the board to point at.
Not a goal
text, charter text, tests and an RFC.
#18127 and is not
touched here.
tracker rule applies only where the board verbs answer.
exists, this change adds only the mechanism that enforces it.
not a new session kind or a new verb.
What changed (motivation → approach → change)
Goal: give the lead a decidable answer for the five calls above.
Approach, over the two alternatives considered. Writing the rules as judgement
("merge when the lines feel entangled") was rejected because it reproduces the
problem in prose. Adding runtime enforcement was rejected as far too large for
guidance that is read before the call is made, and because three of the five
mechanisms already refuse at the server. What is left is to NAME the deciding
mechanism in the document the lead reads first, and to pin that naming with
tests.
What was built:
resource_statusbefore every wave and every reseed wave; queue ontight,criticalorunknown; give capacity back withaction=closeplussession_close; the ceiling is the server'sMAX_SLOTS_PER_CREATORandMAX_LIVE_SLOTS, never a count the lead holdsMAX_DEPTHinwork_ledger.pyis what refuses; the guard admits a depth that does not yet agree with it, so the already-stated one-level tree is the safe one and the cap is never asked to be raisedaction=closeplus a reseed carrying the artifacts;session_adoptis named as what this is NOT, since it moves sessions, sits outside the auto-approved set and is the owner's callcompactledger read comes back cut, items span more than one ledger, or the lead skips items -- answered by ONE worker that writes one summary item and reports, never decidesThe shipped surface is the subtraction of everything already stated. The
charter already carries its own
## Capacitysection and its own one-levelnesting rule, so this adds no second copy of either. Capacity gains exactly one
sentence, inside the section that was already there: a posture of
unknownmeans the reading failed, so it takes the same lighter path as
tight. Theone-level instruction is not restated at all; the skill names only the
mechanism that enforces it and the mismatch being tracked. What the charter
gains as its own section is the three calls it had no text for -- merging two
lines, adding a tracker, and ownership.
The split between the two files follows from that. The skill carries the
reading (when to probe, all four posture words, the ceilings, the trigger, the
refusal to expect); the charter carries one short pointer per rule it did not
already have, because a procedure stated twice is a procedure that drifts until
a reader follows neither copy.
The decision is recorded in the RFC one-pager added here,
docs/request-for-change/rfc-team-lead-management.md, so the reasoning and thetext that implements it land together.
Backwards compatibility
Compatible: the diff adds prose to one skill document and one prompt string,
adds tests, and adds an RFC. No field, key, type, validator or tool signature
changes, so nothing main accepts today stops being accepted.
Removes nothing: the single deleted line is a reflow of the charter's existing
capacity sentence, which is rewritten in place and keeps every instruction it
carried. The repository's own take-away detector agrees -- running
.github/scripts/take_away_check.pyover this diff reports no take-away shape,so no reader list is required.
Tests
A new class,
TestTeamLeadCarriesTeamManagementRulesintest/test_team_lead_agent.py: one test per rule plus a positive control, 6passed.
Each test and the behaviour it locks in:
test_the_probe_reads_both_texts-- the positive control, and it runs first.Every other assertion is an
inagainst two strings, which an empty stringwould satisfy on the absence half, so this one locks in that both texts
arrived with content and that a phrase genuinely absent from both is reported
absent.
test_capacity_gates_every_wave_including_a_reseed-- locks the reading intothe skill (when to probe, all FOUR posture words so a list of three cannot
come back, the two server ceilings) and locks the charter to the single
sentence it gains, so a second copy of the rest cannot be added there.
test_the_depth_cap_is_named_without_restating_the_one_level_rule-- locksin
MAX_DEPTH,work_ledger.py, the tracked mismatch and the no-raiseclause, AND asserts an absence: the one-level instruction must appear in the
skill and NOT inside the new section. That is what keeps this change from
growing a second copy of a rule already stated.
test_merging_two_lines_closes_and_reseeds-- locks the merge to the ledgeroperation and keeps
session_adoptnamed as what it is not.test_a_tracker_is_dispatched_when_one_read_stops_fitting-- locks theconcrete trigger and the reports-never-decides charter.
test_one_owner_per_shared_file_and_one_integrator_per_output-- locks bothhalves plus the separate-reviewer clause.
How the pins are built: the skill text is partitioned down to the
team-management section before the assertions run, so a pinned phrase has to
sit in the rule that owns it rather than anywhere in the file; and every pin is
a mechanism NAME (
resource_status,MAX_DEPTH,work_ledger.py,action=close,session_adopt,reseed wave), so wording can be copy-editedwithout rewriting a test.
The pins were shown to bite after the surface was reduced: rewording the
unknownclause in the charter reddens the capacity test, and removingMAX_DEPTHfrom the skill section reddens the depth test. Each mutation failsexactly its own test, and restoring the files returns 6 passed. No assertion
was loosened to make the reduced surface pass.
Manual verification
N/A -- unit coverage sufficient: the change is document text, and the tests
read the shipped skill file and the installer-emitted charter rather than a
copy, so the assertion target is the artifact a lead actually receives.
Also run locally, all green:
semgrep --config semgrep/over both changedPython files, the comment-history gate against this branch's base (it caught
one real marker in an added docstring, which was rewritten in present tense),
ast.parseonagent.pyafter each prompt edit, and.github/scripts/take_away_check.pyover the full diff.Every mechanism named in the text was grepped in this tree before it was
written:
MAX_DEPTH = 2inwork_ledger.py,MAX_LIVE_SLOTSandMAX_SLOTS_PER_CREATORindashboard/state.py, the fourPOSTURE_*constantsand the failure path that returns
unknowninresource_status.py, the ledgercloseaction, and the comment inagent.pyrecording thatsession_adoptiswithheld from this agent's auto-approved set.
Related Issues
Fixes #18813
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the
Licensing section of CONTRIBUTING.md.