Skip to content

fix(work-ledger): one depth predicate for the three guards, so no sterile conductor - #19715

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/work-ledger-depth-guards-18127
Oct 13, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/work-ledger-depth-guards-18127

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A conductor that may not conduct is refused the moment it is dispatched, never left alive with a ledger it can do nothing in.

A conductor dispatched by a depth-1 conductor comes up sterile. Its ledger opens with a 200, it looks healthy on its parent's board, and then every create it tries is refused with depth_exceeded. The parent sees a child thinking, not a child that cannot start.

Why it matters

Nested dispatch is how a fleet absorbs work it did not know the size of. When the branch is a dead end, the parent should learn at the dispatch, not two patrol cycles later after reading a tail that says nothing happened. The team-lead skill shipped with a paragraph warning leads about this exact trap, which is the cost of leaving it.

Not a goal

  • Changing the number of conducting levels. The cap stays at two: a root conductor and the one conductor it may dispatch.
  • Making the cap configurable.
  • Editing the RFC. Its design text already says what this PR makes the code do.

Intended? / Repro

Intended? No. Every design source says a depth-2 session may only work:

  • docs/request-for-change/rfc-conductor-work-ledger.md § Two-level conductors: "a root conductor may dispatch a conductor, and that child's workers may not conduct."
  • src/kiro_crew/builtin_skills/goal-conductor/SKILL.md: "Depth is capped at 2, so your own children may be workers only — a depth_exceeded on create means flatten, not retry."
  • src/kiro_crew/docs/work-ledger.md: "A conductor may dispatch a conductor only once — depth is capped at 2, so a second-level conductor's own children are workers."
  • src/kiro_crew/dashboard/handlers/work_ledger.py _bootstrap docstring: the refusal "surfaces as depth_exceeded (409) at the moment the child tries to open a ledger, rather than later when it tries to create an item."
  • src/kiro_crew/builtin_skills/team-lead/SKILL.md (merged by the maintainer in feat(agent): ship kirocrew-team-lead as one of the default agents that leads and works #18128) names the disagreement as tracked by work ledger: the three depth guards disagree, so a depth-2 conductor is born sterile #18127.

All three guards landed together in #8855; the test pinning the sterile depth-2 ledger landed in #9152 next to the handler comment that says the opposite.

Repro on origin/main @ 04b59c0. A standalone script against the store with an isolated KIROCREW_HOME:

MAX_DEPTH = 2
child_depth(1) -> 2  (ALLOWS a depth-2 conductor)
ensure_conductor(depth=2) -> opened at depth 2  (ALLOWS)
create at depth 2 -> refused depth_exceeded  (REFUSES)
depth-2 ledger exists on disk: True; items: 0

Same script on this branch:

child_depth(1) -> refused depth_exceeded
ensure_conductor(depth=2) -> refused depth_exceeded
depth-2 ledger exists on disk: False

What changed (motivation → approach → change)

Symptom: a depth-2 ledger opens and then refuses every create. Root cause: MAX_DEPTH was read by three hand-spelled comparisons. child_depth used depth + 1 > MAX_DEPTH, ensure_conductor used depth > MAX_DEPTH, _create_item used depth >= MAX_DEPTH. Two let depth 2 in; one kept it out.

Change: may_conduct(depth) is the one reading of the cap (depth < MAX_DEPTH), and all three guards ask it. The refusal now lands in child_depth, at the grandchild's first ledger call and before any ledger exists for it, so the grandchild's ledger never opens. ensure_conductor and _create_item keep asking the same question for depths that did not arrive through child_depth: a direct call, or a header a crew-log rebuild restored at a depth no entry guard admitted. The MAX_DEPTH comment now says what the number counts and that only may_conduct reads it. The team-lead and goal-conductor skills no longer describe the sterile state or a refusal "at create": they say the child's first ledger call (goal or create) answers depth_exceeded, which is the signal to flatten.

Backwards compatibility

Breaking: a session bound to a depth-1 conductor's item gets 409 depth_exceeded on work_ledger_record action=goal where it got 200 and an empty ledger; its create answers the same 409 it always did. Writer sweep on origin/main @ 1f6f5af: work_ledger.child_depth and work_ledger.ensure_conductor have one caller each, dashboard/handlers/work_ledger.py::_bootstrap, which already maps depth_exceeded to 409 and whose docstring describes this behaviour. No CLI, cron or app code passes a depth.

Reader: src/kiro_crew/dashboard/handlers/work_ledger.py:_bootstrap -- subagent (bound conductor session) -- refusal path already handled; test_a_third_level_conductor_is_refused_at_the_depth_cap
Reader: src/kiro_crew/dashboard/handlers/work_ledger.py:api_work_ledger_get -- crew page, subagent -- a grandchild with no ledger answers 404 no_ledger, the same answer any unopened ledger gives; test_a_third_level_conductor_is_refused_at_the_depth_cap
Reader: src/kiro_crew/work_ledger.py:rebuild_from_projection -- release (crew-log rebuild) -- a stored depth-2 header still rebuilds and still refuses create; test_the_three_depth_guards_agree_at_every_depth

Tests

  • test_child_depth_advances_one_level_and_refuses_the_last_conducting_level — child_depth(1) refuses with depth_exceeded. Red on main (it returned 2).
  • test_ensure_conductor_refuses_the_first_depth_that_may_not_conduct — ensure_conductor(depth=MAX_DEPTH) refuses and writes no record. Red on main.
  • test_create_is_refused_when_a_stored_header_sits_at_a_depth_that_may_not_conduct — a header rewritten to depth 2 on disk still cannot create.
  • test_the_three_depth_guards_agree_at_every_depth (depth 0..3) — for every depth, dispatch, open and create agree with may_conduct.
  • test_a_third_level_conductor_is_refused_at_the_depth_cap (routes) — the grandchild's goal is 409 depth_exceeded, its read is 404 no_ledger, and it can still report as a worker. Red on main (it asserted a 200 and a depth-2 ledger).

Determinism: the tests are pure store calls on a per-test temp home with no clocks, threads or sleeps; CI runs them in both shards' order.

Manual verification

The standalone repro above, run against main and against this branch with the same isolated home. Static gates run locally: black, isort, flake8, mypy, comment-history, builtin-skill-scope, docs-lint, brand, decisions, changelog, feature-map, sync-io, loop-bound-locks, cwd-relative reads — all green. Tests are CI's run.

Related Issues

Fixes #18127

Pattern harvest

Rule candidate: review-prompt
Pattern: one cap constant compared by hand at more than one site (> here, >= there) instead of through one named predicate.

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

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 13, 2026 06:19
@CrysisDeu
CrysisDeu requested a review from mbriones98 October 13, 2026 06:19
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that no existing caller opens a ledger at MAX_DEPTH on purpose. The handler's width probes pass depth=MAX_DEPTH only to size a log line, so they are unaffected.

[DESIGN-REVIEWED] 3d5a7b7

Description read

[DESCRIPTION-READ] facb2b5ad9aa081002aaddd9adf7a3bcd845ceec7327d674f1f14eb58342747a

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 3d5a7b7ce007cc670d40d110a6f16faa385e6a38 — 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: PASS

The new MAX_DEPTH comment says "Read ONLY through may_conduct", but dashboard/handlers/work_ledger.py:1612,1644 also read it, as width probes.

What this change ships

Inventory (7 items) — 7 justified

Intent: when a conductor dispatches a conductor that is not allowed to conduct, the dispatch is refused straight away instead of leaving a child with a ledger it can do nothing in. This is a FIX (#18127).

  1. A conductor dispatched by a depth-1 conductor now gets 409 depth_exceeded on its first goal, where it used to get 200 and a sterile ledger. — justified
  2. Opening a ledger directly at MAX_DEPTH is now refused, and nothing is written to disk. — justified
  3. A new predicate, may_conduct, is the one reading of the cap; all three guards call it (3 consumers). — justified
  4. The depth_exceeded error messages for dispatch and open are reworded. — justified
  5. The team-lead and goal-conductor skills no longer describe the sterile state or a refusal "at create". — justified
  6. The cap's rationale moves from the child_depth docstring onto the MAX_DEPTH comment. — justified
  7. The route test that pinned the opposite behaviour (a 200 with a depth-2 ledger) is rewritten. The description names that pin (feat(work-ledger): kirocrew-work tools and kirocrew-worker agent (phase 2) #9152), cites the handler docstring it contradicted and links work ledger: the three depth guards disagree, so a depth-2 conductor is born sterile #18127. — justified

[FIRST-PRINCIPLES-REVIEWED] 3d5a7b7

Description read

[DESCRIPTION-READ] 6bb7f1e9ad51a0c4b7a891309d3f94a184f47b49283c70678859bd4ebd460d8b

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 3d5a7b7

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

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

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3d5a7b7

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

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 3d5a7b7ce007cc670d40d110a6f16faa385e6a38 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@CrysisDeu
CrysisDeu force-pushed the fix/work-ledger-depth-guards-18127 branch 2 times, most recently from 80db6d7 to 1aecca9 Compare October 13, 2026 07:39
@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • "on the parent's side of the dispatch" contradicts the call path span=3c03ceedeca0

fixed in 1aecca9
The child calls _bootstrap through its own goal/create request and receives the 409; the parent gets no dispatch-time signal.
Reworded the child_depth docstring, the MAX_DEPTH comment and the team-lead skill paragraph to say the refusal lands at the child's first ledger call, before any ledger exists for it. The PR body says the same.

…rile conductor

The three depth guards read MAX_DEPTH with three hand-spelled comparisons and
disagreed about depth 2: child_depth(1) returned 2 and ensure_conductor opened a
ledger there, while _create_item refused every item at it. A conductor dispatched
by a depth-1 conductor therefore came up with a live ledger it could do nothing
in, and its parent read the branch as a slow child, not a refused dispatch.

may_conduct(depth) is now the single reading of the cap (depth < MAX_DEPTH), and
all three guards ask it. The refusal lands at child_depth, on the parent's side,
so the grandchild's ledger never opens; _create_item keeps asking for a header a
crew-log rebuild restored at a depth no entry guard admitted.

Fixes #18127
@CrysisDeu
CrysisDeu force-pushed the fix/work-ledger-depth-guards-18127 branch from 1aecca9 to 3d5a7b7 Compare October 13, 2026 08:18
@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • skills still say the cap is enforced "at create" span=b1a2a704d87a

fixed in 3d5a7b7
team-lead SKILL.md and goal-conductor SKILL.md (both sentences) now say the child's first ledger call, goal or create, answers depth_exceeded; that is where _bootstrap runs child_depth.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 13, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 13, 2026 09:04

@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.

Tier 1 auto-approve: fix (5 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: makes the three work-ledger depth guards read one predicate so a conductor past the cap is refused at its first ledger call instead of opening a ledger that can create nothing; updates the two skill texts and adds tests.

@KiroCrewCaptain
KiroCrewCaptain merged commit 14d05a3 into main Oct 13, 2026
102 of 103 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/work-ledger-depth-guards-18127 branch October 13, 2026 09:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 13, 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.

work ledger: the three depth guards disagree, so a depth-2 conductor is born sterile

2 participants