Skip to content

docs(rfc): one reroute-first ask policy for every crew kind - #37623

Merged
bolichen97 merged 1 commit into
mainfrom
docs/rfc-reroute-first-ask-policy
Nov 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/rfc-reroute-first-ask-policy

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the owner's decision that crew agents reroute first and ask only for five named cases, and that a goal in a turn nobody typed does not wait at the plan gate, so the code in #37609 lands on an accepted RFC.

Crew agents stop and ask the owner too often, even when a fix or a clear recommendation exists. The ask cases are copied about nine times in different words, lessons say they override default behavior, the policy deny notice says to stop, and the goal-conductor Round 0 gate waits for a go-ahead even in a turn no person typed (cron, another session, a patrol wake), where nobody can answer. #37609 changes all of that, and its First Principles review asks for the RFC to be on main first, because an RFC shipped in the same PR does not count.

Why it matters

Without an accepted record, #37609 stays blocked, and the change to every crew kind's default ask and reroute behavior has no decision on file to audit or revert against.

Not a goal

What changed (motivation → approach → change)

Adds docs/request-for-change/rfc-reroute-first-ask-policy.md with status accepted (asked for by the repository owner in the conductor chat on 2026-11-15; takes effect when this document merges) and its row in docs/request-for-change/README.md.

Section Decision
5.1-5.3 One ASK_CORE text at agent rank and in every CRITICAL RULES variant; every other ask list points at (a)-(e)
5.4 A policy block reroutes to an allowed path, else names the exact step and goes on; this notice reaches every session
5.5 Lessons rank under CRITICAL RULES; the header is the same in every session
5.6 A self-set debate or round budget is the conductor's own call unless it spends past an approved amount
5.7 A goal in a turn a gateway marker shows nobody typed skips the Round 0 wait; a person-typed turn is unchanged

Section 6 states the safety holds (no re-spelled blocks, no loosening, approvals and required reviews never bypassed, the plan gate skipped only on a gateway marker). Section 7 has the A/B bench results.

Backwards compatibility

Compatible: documentation only; nothing reads it at runtime.

Removes nothing: it adds one document and one index row.

Tests

Proof: not provable -- docs or config only

scripts/docs-lint.sh passes locally.

Manual verification

N/A — documentation only.

Related Issues

Part of #37606

Implementation: #37609.

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

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Docs-only RFC with a stated rollback; skipping the plan gate removes a chat wait, not an approval.

Notes

  • Section 5.7 has the model spot unattended turns by their opening text in GC prose. An allow-listed channel user, or anyone forwarding text, can type [cron notification and skip the plan gate. Section 6 calls this harmless because tool approvals don't change, but say that this covers channel users too, not only "a person who types a marker by hand skips their own review".
  • Section 7.1 shows long-task unneeded asks going up, 0.10 to 0.24 per run, and the R09/R11/T2 fixes were never re-benched. Before feat(prompts): one reroute-first ask policy for every crew kind #37609 lands, either add a re-bench or say that the replay numbers alone carry the decision.

[DESIGN-REVIEWED] d40eb73

Description read

[DESCRIPTION-READ] 961fca8ac83d40d077341e12c8d40e364085c43764e6cb4d4ae06fd93fe237da

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d40eb73

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d40eb73

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable d40eb730aa7ea8ad77ea54ae51bf6d5944415ace 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 15, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This RFC changes when a conductor waits for a person's go-ahead on its plan. In a turn nobody typed, it would treat the plan as approved and dispatch round 1 at once. A design that lets an agent skip a person's approval step is for the maintainers to decide, so this review does not approve it. A maintainer will post the decision here. The front matter says accepted, but no maintainer comment or review on this PR records that decision yet.

What the review checked on this head:

  • The PR is docs only: one new RFC and one README index row. No runtime code changes.
  • The marker citations resolve on main: _SEND_PROVENANCE in session_messaging.py, the workflow via workflow provenance, and reminder_prompt and heartbeat_prompt in goal_reminder.py.
  • The plan-gate wording the RFC cites exists in the goal-conductor skill, and commits fd07435cc9 and 0fc6bc69d6 exist.
  • The AI review lanes and the Design lane pass. UX and First Principles skipped as expected, and PR Readiness is green.

One thing done well: section 7 reports results that cut against the design, such as the rise in long-task asks and the three fixes that were not re-benched. It does not hide them.

For the security review:

  • Section 5.7 accepts that a goal forwarded through another session's session_send gets no plan gate. The owner sees the plan only in the conductor's first reply, after round 1 has already been dispatched.
  • Section 6 (line 251) says the gate is skipped "only on a gateway marker". But the model matches the marker against the turn's opening text, and line 231 admits that a hand-typed or forwarded marker counts too. Tool approvals and the (a)-(e) ask cases are unchanged, so tool approvals do not move.

Optional:

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 7% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

This PR only adds docs: an accepted RFC and its index row, written so the implementation in #37609 can land on an RFC that is already on main. I checked the RFC's "current state on main" quotes against the code and they are there:

  • output_contract.py:225 says "meaningful quota".
  • deny_notice.py says "say so and stop with the reason" in several places.
  • The lesson headers in learn.py:987 and lessons.py:1214 say lessons "override default behavior".

The gateway markers that section 5.7 relies on also exist where it cites them:

  • _SEND_PROVENANCE in session_messaging.py. Its body goes through _neutralize_send_provenance, so a sender cannot forge a provenance line inside the message.
  • The cron, monitor, work-ledger and auto-nudge prefixes in _INJECTED_PREFIXES.
  • The workflow envelope in workflow_session_port.py.
  • The reminder and heartbeat prefixes in goal_reminder.py.

Trust check: the Round 0 plan gate is a chat wait, not an approval. A person can already skip it by typing "go ahead". Tool approvals, the sandbox and the deny gate stay unchanged, so someone who forges a marker gains nothing they couldn't already get by typing "go ahead". The trust boundary do

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit d40eb730aa · 331 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Design review of the RFC and its README row. I read the whole diff on this head (docs only, no code). I did not run tests locally and did not re read the code citations on main.

What it is. One ASK_CORE text replaces about nine differently worded "when to ask the owner" lists. Every crew kind reads it at agent rank and in every CRITICAL RULES variant. It says: take another allowed path first, act on a clear best option and report it, ask only for five named cases (a) to (e), and keep the safety holds. Section 5.7 also skips the Round 0 plan gate in a turn nobody typed, detected by a fixed gateway marker at the start of the turn.

Pros

  • One source of truth instead of copies that drift, with a test that the list wording lives only in output_contract.py.
  • The replay bench moves over asks from 18/55 to 9/55, and all 20 control moments where asking is right still ask.
  • Section 5.7 changes only prompt text. The markers it relies on already exist in code, and a marker quoted inside a tool result or file does not count.
  • Blocks are never re spelled: the same effect by another tool is still the blocked action, and approvals and required reviews are not bypassed.

Cons and risks

  • Long task unneeded asks per run went from 0.10 to 0.24. The RFC says the sample is too small to tell, so it shows no gain there.
  • Bot moments with lessons loaded only move from 10/15 to 8/15.
  • The three fixes in 7.3 were not re benched (the RFC lists this as an open question).
  • A goal the owner types into session A and A forwards with session_send now runs without the plan gate. The RFC accepts this and says why.
  • The deny notice and lesson header changes reach every session, not only crew sessions. Always on guidance grows by about 1.1k to 1.5k characters per crew kind.

Tech debt. The two re bench items in section 11. The README row is a long "verified at" entry that will need a re audit when #37609 lands.

Recommendation. Worth doing, and the direction (reroute before asking, five fixed ask cases) is sound. Because this is a design RFC that changes the deny notice wording and the plan gate, I am leaving it as a comment and not approving. It needs the maintainer sign off on the direction, and the implementation PR #37609 should follow the same sign off. All 96 checks are green.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Direction signed by maintainer (bolichen97), 11-15 PST.

Approving the RFC and its README row. I read the whole diff on this head earlier (docs only, no code), and the head has not changed since. All 97 checks are green. I did not run tests locally and did not re read the code citations on main.

Two notes for the implementation PR (#37609). Neither blocks this document:

  1. Re measure the unneeded question rate with a bigger sample. The long task bench shows 0.10 unneeded asks per run on main and 0.24 on the new design, and the RFC itself says the sample is too small to tell them apart.
  2. The deny notice wording change must not refuse anything main allows. It should only change what the agent says after a block, not which calls are blocked.

@bolichen97
bolichen97 merged commit 2041e86 into main Nov 15, 2026
98 checks passed
@bolichen97
bolichen97 deleted the docs/rfc-reroute-first-ask-policy branch November 15, 2026 17:15
@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.

3 participants