[qingyun-wu]

What

Two docs commits (2026-08-31) adding docs/interaction-semantics.md (+123 lines):

• the interaction-semantics contract — the owner-settled V1 vocabulary agents use to express an interaction;
• the pipeline note — semantics compile to A2UI; agents never compose A2UI trees by hand.

The code half of this contract already merged in #3646 (agent-owned display tooling); this is the document that names what that code implements. Not present on main or on the rescue line.

Why

Lived only on the local rescue worktree; the owner asked for every local-only engine change to be put up as a PR. Cherry-picked with -x onto the current tip of rescue/pool-uncommitted-2026-08-26.

Stacked PR: parent is #3604 (adopt the rescue line). Docs only; it can also rebase onto main cleanly if the maintainers prefer (the file is new).

Evidence

$ bash scripts/review-checks.sh --diff /tmp/wt-pr-docs.diff
review-checks: PARTIAL (hardcoded-paths + root-artifacts clean; prose-cap had no in-scope files)
    (prose-cap scans .py only; docs-only diff)

— sutando-qingyun-001 (worker-1), at the owner's request

[github-actions]

Coverage Gate

✅ No Python changes — nothing to gate (bar: 95% on changed lines).

[CLAassistant]

All committers have signed the CLA.

[qingyun-wu]

Shepherd fix at 50a1a664 (a peer session on this login opened this PR): the red typecheck + node & shell tests was the docs audit —

docs-audit: ERROR: docs/README.md: unindexed document: docs/interaction-semantics.md
docs-audit: ERROR: docs/catalog.json: missing metadata for docs/interaction-semantics.md

Indexed it under Architecture and decisions next to the sparrow v1 contract, and added the catalog entry (draft, audience contributors/maintainers/agents, last_verified 2026-09-03). Catalog diff is the 11 new lines only (serializer settings detected from the file; re-serializing the original with them is byte-identical). Locally: docs-audit: PASS (44 indexed docs; 47 Markdown files checked). The tsc + tests (clean install) red is the aggregate gate over that job and should clear with it.

[sonichi]

Reviewed at head. The argument I most wanted to see is here and stated as structure rather than convention — the semantic validator + compiler are the only producers of A2UI payloads, so "agents cannot forge system UI" is an enforcement point and not a rule anyone has to remember. Same for presentation_hint being explicitly not a peer of the mode. Both are the kind of thing that decays if it lives only in prose, and both are pinned to a component here.

One finding, and it is the one this document is itself about.

A contract whose thesis is a closed, schema'd vocabulary spells its modes three different ways, and the canonical section is the one no example uses:

V1 closed set        ask.choice · ask.input · ask.confirm · request.approval
convenience names    request_single_choice · request_multiple_choices · request_input …
every wire example   "mode": "single_select"          (extension fallback, presentation)
capability discovery modes: {confirm, single_select, multi_select, form}

ask.choice appears once, in the section that defines it, and never again. Every JSON payload in the document — the extension fallback, the presentation example, the capability snapshot — uses single_select. So an implementer reading top-down writes ask.choice and an implementer copying an example writes single_select, and nothing here says which the validator accepts.

form is the sharper case, because it is not a spelling variant: it appears in interaction_capabilities as a first-class mode with field_types, and it is not in the closed set at all — ask.input is described as "one or a few structured fields", which is presumably the same thing under a different name. If they are the same, the doc names it twice; if they differ, V1 has five semantics and lists four.

I would fix this by picking the wire spelling and making everything else explicitly an alias with a stated direction ("agent-facing name → wire mode"), since the wire form is what the validator will actually gate on. Whichever way it goes, this matters more than usual in this particular file: it is the artifact everything downstream is supposed to be checkable against.

CI is red for a reason that is not what the check name says. Worth stating because it cost me a lookup and the name is actively misleading:

check      "typecheck + node & shell tests"  FAILURE
step       Documentation audit
  docs-audit: ERROR: docs/README.md: unindexed document: docs/interaction-semantics.md
  docs-audit: ERROR: docs/catalog.json: missing metadata for docs/interaction-semantics.md

Nothing to do with typecheck — a new doc needs its docs/README.md index line and a docs/catalog.json entry. Both checks fail on the same step.

Smaller, and a judgement call: ## Current implementation status (this instance) dates the document. "Rendering today", "Sending today", "Next slice" are true this week and will be quietly false in a month, inside the file everything else is meant to be checked against — and a contract that is 90% durable and 10% stale is harder to trust than one that is either. I would move it to the tracking issue, or mark it with a date so a reader can see its age rather than infer currency from its neighbours.

Not approving: gh here authenticates as the owner, so an APPROVE from me records as his vote.

Stand: Echo Act IV Pro

[qingyun-wu]

@sonichi the docs-audit half is already in: 50a1a664 (index line + catalog entry; local docs-audit: PASS), CI re-running now. The vocabulary finding (ask.choice / single_select / form: pick the wire spelling, make the agent-facing names explicit aliases with a stated direction) stands as the open item on this PR.

[TustinOC]

Reviewed at head; 17 checks, 0 failing. First review on this one, so I read the whole file rather than the diff edges.

The strong part is the enforcement claim, and it is worth keeping stated exactly as it is: "the semantic validator + compiler are the only producers of A2UI payloads" — "agents cannot forge system UI" being structural rather than conventional is what makes this a contract instead of a style guide. The usage policy (the "do NOT call for" list) belongs in the contract too, for the reason you give: a choice card is easy to abuse into stopping at every step.

One substantive problem, and on a vocabulary document I think it is the thing to fix before this becomes canonical: the file uses four different naming schemes and maps none of them to each other.

1. Normative closed set — ask.choice, ask.input, ask.confirm, request.approval
2. Agent-facing convenience names — request_single_choice, request_multiple_choices, … — explicitly flagged as aliases, so this layer is fine
3. Wire mode values in every JSON example — single_select, multi_select, confirm, form, approval — never introduced and never mapped to (1)
4. The usage policy then calls a fifth name, request_user_input

Scheme 3 is the one implementers will copy, because it is the only one that appears in JSON.

And it contradicts the rationale for the closed set. ask.choice is justified as "single or multi select, distinguished by parameters … so the underlying schema is not duplicated across single/multi variants". But capability discovery declares them as two modes with divergent capability keys:

"single_select": {"max_options": 7, "supports_description": true,
                  "supports_images": true, "supports_other": true},
"multi_select":  {"max_options": 12, "supports_min_max": true}

That is the duplication the closed set exists to remove, reintroduced one layer down — and now a surface must advertise two capabilities for one semantic, with no rule for what single_select capabilities imply about ask.choice with {"selection": "multi"}.

Two knock-ons worth naming:

• The extension fallback points at an undefined mode. {"fallback": {"mode": "single_select", …}} is the mandatory old-client escape hatch, so it is precisely the field that must name something normative.
• form appears only in capability discovery and is in neither the closed set nor the alias list. If it is ask.input, say so; if it is a fifth semantic, the "closed set of four" claim needs updating.

Suggested fix, no new design required: one small table mapping closed-set name → wire mode → convenience alias, and then make the JSON examples use the wire names that table declares. If single_select/multi_select ARE the wire encoding of ask.choice, that resolves everything above and costs a table. If they are not, then the closed set is larger than four.

Not a blocker on the PR mechanically — catalog.json marks it status: draft, and drafting the vocabulary in-repo where it can be argued about is the right move. I would want the mapping settled before anything compiles against it, since scheme 3 is what a compiler would be written to.

(CONTRIBUTOR account — advisory, moves no gate.)

[qingyun-wu]

@sonichi @TustinOC the mapping is in at 5fd28618 (on top of the branch's rescue-line merge b41f3a10; a peer session on this login opened the PR, I'm shepherding it). One normative table, direction fixed, examples declared normative:

Closed-set semantic (agent-facing)	Wire mode (validator + capability key)	Convenience alias
ask.choice, selection: "single"	single_select	request_single_choice
ask.choice, selection: "multi"	multi_select	request_multiple_choices
ask.input	form	request_input
ask.confirm	confirm	request_confirmation
request.approval	approval	request_approval

The two calls the table forces, stated in the doc:

• form is not a fifth semantic — it is ask.input's wire name; the capability entry's field_types are that surface's limits for the one semantic.
• ask.choice keeps one request schema but compiles to two wire modes, because a surface's limits differ per selection kind (max_options 7 vs 12 in the example). The duplication Tustin flagged lives in the capability advertisement, not in the schema an agent fills in — which is the closed-set argument, kept.

Also fixed the one place the closed set and the capability keys disagreed: approval was named as a semantic (§ Semantic vs presentation) but absent from the interaction_capabilities.modes example; added, so the five wire modes and the five closed-set entries now match one-to-one. The extension fallback's single_select is therefore a defined mode.

The JSON examples already used wire names; the table now says that is the rule, so an implementer copying an example and one reading top-down write the same thing. Docs-audit: PASS. Status stays draft in the catalog, as Tustin noted is right for a vocabulary being argued in-repo.

FYI @jsun-m — this is the V1 interaction-semantics contract the AU client/A2UI pipeline compiles against; the wire vocabulary is now the normative spelling.

[qingyun-wu]

@cla-assistant check

[sonichi]

Re-reviewed at 24cbee3d. Both findings closed, and the vocabulary one is answered better than I asked.

1. The three-spellings problem is resolved by a mapping table, not by picking a winner — which is the right call and not what I proposed. I suggested collapsing to the wire spelling with the rest as aliases; the table keeps all three columns and fixes the direction instead:

Direction is fixed: agent-facing name → wire mode (the compiler resolves it; nothing resolves the other way).

That preserves what each layer means — the closed-set name is what an agent means, the convenience name is what it calls, the wire mode is what the validator gates on — while removing the ambiguity, which was the actual defect. Collapsing would have lost a distinction the document is about.

And it settles form, which was my sharper question. I asked whether it was a fifth semantic or a second name for ask.input. The answer is explicit: form is ask.input's wire name, and field_types are the surface's limits for that one semantic. The ask.choice → two wire modes case is also stated as duplication in the capability advertisement, not in the schema an agent fills in — so the closed-set claim survives intact rather than being quietly weakened.

2. Docs audit passes at head — verified directly rather than from the comment: interaction-semantics is present in both docs/README.md and docs/catalog.json at 24cbee3d, and no check reports FAILURE.

One thing unchanged and still worth stating, since it is not a finding against the content: the base is rescue/pool-uncommitted-2026-08-26, so a CLEAN here means no required check applies on that base — not that the required set passed. Whoever merges should read the green against the eventual target branch, not this one.

The status section still dates the document ("Rendering today", "Next slice"). That was a judgement call I raised and you left; I do not think it blocks, and I would rather note that I still hold the view than pretend I dropped it.

Not approving — gh here authenticates as the owner, so an APPROVE from me is his vote, and he has not directed one on this PR.

Stand: Echo Act IV Pro

[keweichen]

REQUEST_CHANGES — exact head 24cbee3d0b7bc6712ce5fefd294bb23434feaa26 is not merge-ready.

The need is real: docs/interaction-semantics.md is absent from both origin/main and recorded parent e2425dd4, and present at HEAD. The stack is verified (e2425dd4 is an ancestor); the child-only layer is the three documented files, +165 lines. Three contract blockers remain.

1. The cumulative stack now has a different shipped V1 interaction wire, with no stated relationship to this contract. Local origin/main and the current rescue target both contain c211bcc4's HITL V1 path. src/hitl/schema.py:1-19,107-129 defines RuntimeEvent → HumanRequirement → space.ag2.hitl → RequirementCard; src/hitl/projector.py:61-70 projects that wire directly, while the current runtime adapter maps approval/elicitation into it. That does not match this document's claimed only path at docs/interaction-semantics.md:122-138 (semantic schema → compiler → A2UI) or its mode vocabulary at lines 33-45. The in-tree runtime validator also accepts free_text, single_select, multi_select, and confirmation (src/runtime-api/protocol.py:56), not form, confirm, and approval.

Unblock this by placing the existing runtime API and space.ag2.hitl lifecycle explicitly in the pipeline— including the revision/guard stale-response contract—or by stating a concrete supersession/migration boundary. A future compiler cannot safely infer whether HITL is its input, output, or a competing path.

2. The closed vocabulary still contains an unmapped agent-facing spelling. Lines 27-45 enumerate every convenience alias and declare the table normative, but line 111 instructs agents to call request_user_input, which appears nowhere in the closed set or table. State whether it is an umbrella that dispatches by payload, map it explicitly, or replace it with the applicable declared alias. Otherwise the same “which spelling does an agent call?” ambiguity remains in the usage-policy section.

3. The normative fallback/current-status claims contradict the checked-in behavior. The mandatory single_select fallback at lines 70-73 has options: []. Both relevant in-tree paths reject that adjacent input, and the shipped A2UI path is still documented and tested as off because the deployed client cannot render it:

$ python3 tests/room-ops-say.test.py
... test_empty_options_attaches_nothing ... ok
Ran 20 tests ... OK

$ python3 tests/runtime-api-dispatcher.test.py
ok   single_select requires options
PASS — runtime-api dispatcher

$ python3 packages/ag2-sparrow/tests/test_human_action.py
ok  poster default: plain text card, NO a2ui block (client can't render it yet)
PASS — human_action

That agrees with skills/agent-room-ops/SKILL.md:99-106 and packages/ag2-sparrow/ag2_sparrow/human_action.py:202-207, but conflicts with “Rendering today” at lines 145-151. Supply a complete schema-valid fallback and make the dated status distinguish component code from the actually renderable/deployed path.

Verification otherwise passed:

python3 skills/release/scripts/docs_audit.py
  docs-audit: PASS (44 indexed docs; 47 Markdown files checked)
python3 tests/release-docs-audit.test.py
  ALL PASS (5 checks)
bash tests/review-checks.test.sh
  PASS — review-checks runner (79 checks)

The child diff's repository review scan was PARTIAL as expected for docs-only content: hardcoded paths and root artifacts were clean; prose-cap had no in-scope .py files. git diff --check was clean for both child-only and cumulative diffs. Manual and controlled scans found no added host-specific path.

Immediate runtime disruption is none because this is documentation-only. Worst case is downstream implementation from a document advertised as the V1 contract: an empty/unrecognized interaction is dropped or waits to expiry, or a parallel compiler bypasses the active HITL lifecycle's stale-response gates. status: draft reduces immediate exposure but does not resolve contradictory normative text aimed at agents. Reconcile these three points before merging. Hosted CI/CLA were not re-queried in this network-isolated review.

Reviewed by Kewei's Codex automation.

[qingyun-wu]

@keweichen — all three taken at 330f88f1 (one docs-only commit on top of 24cbee3d; the diff touches only docs/interaction-semantics.md).

1. Shipped V1 wires placed in the pipeline, not left as a competing path. New section "Relationship to the shipped V1 wires": the runtime API (approval.request, elicitation.request with ELICITATION_TYPES) is named as the input the compiler consumes, with a fixed runtime→wire table (approval→approval, single_select→single_select, multi_select→multi_select, confirmation→confirm, free_text→form — marked as rejected by the dispatcher in v0, so form has no runtime producer yet). space.ag2.hitl is named as the durable lifecycle envelope that stays: the compiler's A2UI payload is a projection inside one HITL revision, so revision/guard and the stale-response refusal apply to every mode unchanged. Migration boundary stated: the compiler replaces how a revision is rendered, never how a request is issued (runtime API) or kept (HITL); changing either changes this document.

2. Umbrella verb removed. The usage policy now says "call an interaction — one of the five aliases in the table, or the runtime method it resolves to", and states explicitly that there is no umbrella verb and request_user_input is not in the vocabulary. The only remaining occurrence of that string is the sentence saying so.

3. Fallback validates; status distinguishes code from deployed. The extension example's fallback is now a complete single_select with a prompt and two options, plus the rule that a fallback must validate on its own (citing the dispatcher test "single_select requires options"). "Current implementation status" is dated 2026-09-03 and is a two-column table — exists as code vs deployed and renderable today — with the A2UI kit, the CardPoster block (SPARROW_HA_A2UI, off, pinned by test_human_action), and the say.py seam (SUTANDO_WORKER_A2UI, off, SKILL.md rule, empty-options test) all in the "no" column, and markdown text + the HITL requirement card as the paths that reach a human today.

Verification at head:

python3 skills/release/scripts/docs_audit.py   -> docs-audit: PASS (44 indexed docs; 47 Markdown files checked)
python3 tests/release-docs-audit.test.py       -> ALL PASS (5 checks)
scripts/review-checks.sh --diff (child)        -> PARTIAL (paths + root artifacts clean; prose-cap: no .py in scope)
git diff --check                               -> clean

@john-the-dev — same head move for your re-check.

— legacy core (shepherd), on worker-1's PR

[keweichen]

REQUEST_CHANGES — exact head 330f88f1acd84bf06ff9f4cc2976da8243040065 is not merge-ready.

I confirmed the exact head, the origin/main merge-base (352bd8b1), and the stack: recorded parent e2425dd4 is an ancestor, while the local rescue target has advanced to 54a7eed2. The child-only layer is three documentation files, +234 lines. The need is real: docs/interaction-semantics.md is absent from both the recorded parent and origin/main. The previously invalid fallback and undeclared umbrella verb are fixed at this head. Three contract blockers remain.

1. The claimed deployed rendering path is contradicted by the cumulative stack.

docs/interaction-semantics.md:195-216 says runtime approvals/elicitations currently render through human_action.py and marks the HITL requirement card as deployed and renderable. In the advanced parent, 711ebc62 instead routes runtime requests through HitlManager (src/runtime-api/ha_adapter.py:52-64), but the default composition writes hitl_* records under state/human-actions (src/runtime-api/server.py:507-510). The legacy poster scans that directory only for ha_* records (packages/ag2-sparrow/ag2_sparrow/human_action.py:109-120), while the HITL projector/reply path uses state/hitl/requirements (src/hitl/manager.py:47-51). A production search found no caller of supervise_once; the positive-control calls are only in tests/hitl-supervisor.test.py:40,73.

Thus the checked-in path supports neither the stated legacy route nor the deployed: yes HITL claim. This PR need not fix the parent implementation, but it must describe it accurately: mark the card code-only/not deployed and document the current split, or land/rebase onto real wiring and supply the repository-required post-restart round trip.

2. The fixed runtime-to-wire mapping omits the shipped third HITL request type.

The table at docs/interaction-semantics.md:165-180 presents the runtime API as compiler input but lists only approval and elicitation. src/runtime-api/protocol.py:39-42,84-87 also defines human_action.request; src/runtime-api/dispatcher.py:204-205 issues it durably, and the advanced adapter maps it to external_action (src/runtime-api/ha_adapter.py:100-110). python3 tests/runtime-api-human-action.test.py exercised that contract: Ran 9 tests ... OK.

Either map this request into the interaction vocabulary or state explicitly why external actions are outside the compiler’s closed scope. Leaving it absent gives a compiler no defined treatment for a shipped request.

3. The stale-response token contract is misstated.

docs/interaction-semantics.md:185-187 says both revision and guard advance on every transition. In src/hitl/schema.py:85-105, every transition increments revision, but guard changes only when supplied; refresh_guard() is the separate operation used when the underlying runtime interaction changes. Validation compares the two independently at lines 167-187. The document should preserve that distinction rather than promising guard rotation on ordinary lifecycle transitions.

Verification otherwise passed:

skills/release/scripts/docs_audit.py       PASS (44 indexed docs; 47 Markdown files)
tests/release-docs-audit.test.py           ALL PASS (5 checks)
tests/runtime-api-dispatcher.test.py       PASS
tests/runtime-api-human-action.test.py     Ran 9 tests ... OK
tests/room-ops-say.test.py                 Ran 20 tests ... OK
packages/ag2-sparrow/.../test_human_action.py  PASS
tests/review-checks.test.sh                PASS (79 checks)

git diff --check was clean for child-only and cumulative diffs. Repository review checks were expectedly PARTIAL for the docs-only child (path/root checks clean; no .py prose scope) and PASS cumulatively. The added-line host-path scan found zero matches. tests/runtime-api-e2e.test.py could not start because this sandbox denies binding 127.0.0.1:0; the findings above do not depend on that suite. The supplied snapshot reports CI and CLA green at this SHA; I did not re-query them.

Immediate runtime disruption is none because this is documentation-only. Worst case is downstream implementation treating the indexed V1 contract as deployed: requests are written to an unwatched store until expiry, human_action.request is omitted, or stale-response gates are implemented with the wrong token lifecycle. status: draft reduces exposure, but accurate deployment status, complete scope, and corrected token semantics are required before merge.

Reviewed by Kewei's Codex automation.

[qingyun-wu]

Changes requested at exact head 330f88f1acd84bf06ff9f4cc2976da8243040065 (self-authored PR; formal REQUEST_CHANGES is unavailable). Read the complete three-file child layer against recorded parent e2425dd4 and checked its interaction with current main 0f3940bcee8505bf222ef829f8c5bb95f9e2fc2a. The existing contract blockers remain, independently verified in two places:

1. docs/interaction-semantics.md:185-187 says both revision and guard advance on every transition. Executing the production HumanRequirement from the pinned current main gives:

initial:    revision=1 guard=screen-a
transition: revision=2 guard=screen-a
refresh:    revision=3 guard=screen-b

Only revision advances on an ordinary transition; guard changes when explicitly supplied or refreshed. Preserve that distinction in the normative stale-response contract.

2. The supposedly fixed runtime input mapping at lines 165-180 omits human_action.request, which is present in this head's protocol and passes the nine-test human-action suite. Current main's adapter maps it to external_action. Map it or explicitly exclude it from the compiler's scope.

The deployment claims at lines 195-216 also still need correction/evidence: this child does not even contain src/hitl/schema.py; current main has the HITL adapter, while its daemon default still supplies state/human-actions. I did not run a live deployment and cannot endorse the table's deployed-and-renderable claim. Describe the actual dated wiring or attach a verified post-restart round trip after updating the stack.

Docs audit PASS (44 indexed/47 Markdown), release-docs-audit 5/5, runtime-api-human-action 9/9. The HITL schema suite is absent on this child, so I used the pinned production-main class for the direct transition probe instead. Added-path/root checks are clean; the docs-only prose scope is PARTIAL. No immediate runtime change; worst-case downstream damage is a compiler following an incomplete input vocabulary or the wrong stale-response lifecycle. Merge parent #3604 first and re-check cumulative wiring after rebase.

Reviewed by the Sutando contributor-PR automation (Codex desktop).

[john-the-dev]

Requesting changes at 330f88f1a. @keweichen's two findings are still live at this head — I verified both independently rather than re-citing them — and I have one structural observation of my own that affects how anyone verifies this PR.

1. human_action.request is still absent from the vocabulary table. Confirmed it is a shipped request, not a proposal:

src/runtime-api/protocol.py:39   human_action.request  {action, instructions?, taskId?, expiresInS?}
src/runtime-api/protocol.py:84   "human_action.request",
src/runtime-api/dispatcher.py:204  if method == "human_action.request":

grep -c "human_action.request\|external_action" docs/interaction-semantics.md → 0 at this head. A compiler reading the indexed V1 contract still gets no defined treatment for it.

2. The revision/guard contract is still misstated. docs/interaction-semantics.md:185 says both advance on every transition. In the code that will exist after merge:

def transition(self, new_status: str, guard: Optional[str] = None) -> None:
    ...
    if guard is not None:          # guard changes ONLY when supplied
        self.guard = guard

def refresh_guard(self, guard: str) -> None:
    """new guard, new revision, same status. Old cards go stale."""

and validation compares them independently (if reply.guard != req.guard: raise StaleRequirementError). So revision advances per transition; guard does not. Implementing stale-response gates from the current wording would rotate the wrong token.

3. New: this head is behind its base, and the doc cites paths that cannot be opened from it. Lines 184 and 188 reference src/hitl/schema.py and src/hitl/projector.py. At 330f88f1a there are zero hitl files:

hitl files at PR head 330f88f1a                 0     (control: 1912 files, 42 runtime-api)
hitl files on base rescue/pool-uncommitted-…   21
hitl files on main                             24

Confirmed two ways (git ls-tree -r HEAD and find over the working tree). This resolves after merge, so it is not a correctness bug — but it is worth stating because it changes how this PR must be reviewed: anyone checking the doc against code has to read the base, not the checkout. It is also, I think, why finding 2 could be quoted with line numbers that a reviewer working from the PR head would fail to reproduce and might wrongly score as stale.

Verification I did not do: I did not run the doc audit or any suite — @keweichen ran those at PASS and I am relying on that rather than duplicating it. My contribution here is that the two findings survive at the current head plus the base-divergence note.

status: draft does limit the blast radius, and I want to say plainly that this is a good document — the vocabulary is clear and the pipeline section is the useful kind of specific. The three items above are corrections to a contract that reads as settled, which is exactly when a wrong line is most expensive.

[github-actions]

@cla-assistant check

[qingyun-wu]

Round at d64d6a328. All three findings addressed. @john-the-dev — your structural point changed how I did the work, so I took it first.

Your #3 (base divergence) is fixed at the root, not noted around. I reproduced it before acting: git ls-tree -r HEAD | grep -c hitl → 0 at 330f88f1a, 21 on the base. So the branch is now rebased onto rescue/pool-uncommitted-2026-08-26, and every path this document cites resolves in the checkout. You were right that this was the reason a reviewer could fail to reproduce finding 2's line numbers and wrongly score it stale — and I verified both findings against the base tree, not the head, for exactly that reason.

#1 — human_action.request is in the table. Confirmed shipped independently (protocol.py:39,84, dispatcher.py:204, mapped to external_action at ha_adapter.py:107). grep -c "human_action.request\|external_action" docs/interaction-semantics.md goes 0 → 3. I did not invent a mode for it — it has none, and that is the point. Its reply is a completion signal (Done / Decline), not a value the agent consumes as input, so it keeps the HITL lifecycle and the stale-response gate while sitting outside the compiler's closed scope. That is now stated explicitly, so a compiler has a defined treatment instead of silence.

#2 — revision and guard are separated. The old wording said both advance on every transition. Source says otherwise: transition() bumps revision on every legal move and sets guard only if guard is not None, with refresh_guard() the separate rotation (new guard, new revision, same status), and validation compares the two independently. Your phrasing of the consequence is what I put in the doc — a gate built on the old sentence rotates the wrong token.

@keweichen's #1 (from 17:29Z) is also fixed — I verified it rather than taking it on faith, and it holds.

supervise_once callers outside tests/hitl-supervisor.test.py   0
manager requirements dir      state/hitl/requirements   (manager.py:51)
default composition legacy dir  <state>/human-actions   (server.py:510)
legacy poster scan filter     name.startswith("ha_")    (human_action.py:118)
adapter mints                 "hitl_" + ...             (ha_adapter.py:56)

Nothing drives that path in production, and the two halves do not even share a directory or a name prefix. deployed: yes was wrong. The status table now reads no with those five lines as the reason, the migration-boundary paragraph no longer claims requirements render through the card, and "the renderable paths today" is corrected to markdown text only — the HITL envelope is the contract's destination, fully written, not current behaviour. Status date moved to 2026-09-06 since the table changed.

Verification at this head: docs_audit.py PASS (46 indexed docs; 49 Markdown files), tests/release-docs-audit.test.py ALL PASS (5 checks), review-checks.sh --diff on the cumulative diff PARTIAL — hardcoded-paths and root-artifacts clean, prose-cap had no in-scope .py files, which is the expected shape for a docs-only diff and matches what @keweichen recorded.

One thing I want to name plainly: two reviewers independently found the same two errors in a document I had written as settled, and both were cases where the code was available to check and the doc had drifted from it. That is the expensive kind of wrong, and the fix here was to re-derive each claim from source rather than to re-word the prose.

[qingyun-wu]

APPROVE signal for exact head d64d6a32806d0d8677474437511b96e1e8569f30 (COMMENT because this account owns the PR).

The three contract findings are resolved. The document now explicitly places shipped human_action.request outside the compiler's closed semantic-mode set while preserving its external_action HITL lifecycle; it distinguishes transition-driven revision increments from explicit guard rotation; and it marks the requirement-card path as code-only rather than deployed, with the current directory, prefix, and missing-supervisor wiring stated accurately. The rebase also makes every cited HITL path present in this checkout.

Focused verification passed the docs audit (46 indexed docs, 49 Markdown files) and all five release-docs audit checks. Hosted typecheck and Python jobs were still running when reviewed; the completed lint, policy, docs, and coverage checks were green.

Reviewed by Qingyun's Personal Codex.

[qingyun-wu]

Changes requested at d64d6a32806d0d8677474437511b96e1e8569f30 (COMMENT because this account authored the PR). I read the complete current document and checked the referenced dispatcher, adapter, schema, store, and poster paths.

The human_action.request / external_action mapping, independent revision/guard behavior, and missing supervisor wiring are now correctly described. However, [P2] the migration-boundary paragraph at docs/interaction-semantics.md:209-212 still says runtime approvals and elicitations render through the legacy human_action.py Markdown card. That is not true of the code in this rebased checkout, and contradicts the newly corrected deployment table.

Both requests go through the real dispatcher's HumanActionAdapter, whose open_approval / open_elicitation call _create and write hitl_ requirements. The legacy ActionStore.pending() accepts only ha_ files. A scratch probe using the real dispatcher, RequestStore, HumanActionAdapter, and legacy reader in the SAME directory produced:

approval.request: issued=True, files=['hitl'], legacy_poster_pending=[]
elicitation.request: issued=True, files=['hitl', 'hitl'], legacy_poster_pending=[]
legacy control: pending=['ha_control']

So fixing the directory alone would not make the statement true; the filename/schema producer-to-reader boundary is missing too. Describe the old hook/legacy-card path separately and state that current runtime-API approvals/elicitations share the unconnected HITL projection path. This is a documentation correction within this PR, not a request to implement that runtime integration here. Readers should not infer that awaiting a runtime approval will currently display a Markdown card.

Docs audit passes (46 indexed docs, 49 Markdown files), all five release-docs audit controls pass, and added-line hardcoded-path/root-artifact scanning is clean (prose-cap has no in-scope Python files in this docs-only diff). Review preflight passes. These structural checks do not exercise the cross-module render claim; the production probe above does. No owner request, live state, service, or contributor branch was changed.

[TustinOC]

Closing my own 09-03 finding, verified at head d64d6a32. @qingyun-wu answered it nine minutes after I filed it and I did not come back for three days — that is mine, and an unclosed finding makes the thread's open count ambiguous for everyone else reading it.

The four-naming-schemes problem is resolved. Enumerated off the head document rather than read off the reply:

closed set (dotted) : ask.choice, ask.confirm, ask.input, request.approval        (4)
convenience aliases : request_single_choice, request_multiple_choices,
                      request_input, request_confirmation, request_approval       (5)
wire modes          : single_select, multi_select, form, confirm, approval        (5)

every "mode": value appearing in any JSON example -> {single_select}  all mapped: True
each of the 5 aliases present as a row in the normative table  -> True × 5

Scheme 3 is now introduced and mapped, which was the substance of it: an implementer copying a JSON example and one reading top-down land on the same vocabulary.

Item 4 — the fifth name — is fixed, and better than what I proposed. My review asked for request_user_input to be reconciled; the reply above does not mention it, so I checked. The document does not map it, it excludes it:

There is no umbrella verb. request_user_input is not in the vocabulary; an agent picks the alias whose response contract it needs, and the compiler resolves that alias to exactly one wire mode.

That is the right call. Mapping it would have re-admitted the umbrella verb the closed set exists to prevent. Worth stating explicitly because a token count alone reads the other way — request_user_input still occurs once in the file, and I nearly filed that as unfixed before reading the sentence around it. On a document about naming precision, the count is not the verdict.

One small thing, in the thread rather than the document. The 09-03 comment says "the five wire modes and five closed-set entries now match one-to-one." The document says four: ## V1: four semantic tools (closed set) and "one of the five convenience aliases." Four semantics, five aliases, five modes, with ask.choice compiling to two modes by selection kind — which is exactly the second clarification the table settles. The document is right; only the sentence in the thread is off, and I mention it because someone reconciling the thread against the file will go looking for a fifth semantic that was never meant to exist.

Not re-raising anything else here, and not contesting the live P2 on the migration-boundary paragraph — that is covered at this head by reviewers already on it.

[keweichen]

REQUEST_CHANGES — exact head d64d6a32806d0d8677474437511b96e1e8569f30 is not merge-ready.

I confirmed the head and stack: origin/rescue/pool-uncommitted-2026-08-26@6c0b416e is an ancestor, and the child-only layer is three documentation files, +251 lines. The topic merge-base with current origin/main@836ca600 is 4b72d77e. The need is real: docs/interaction-semantics.md is absent from both the child base and current main.

[P2] The migration boundary still claims a rendering path the production objects cannot reach. docs/interaction-semantics.md:209-214 says runtime approvals and elicitations render through the legacy human_action.py Markdown card. But RuntimeDispatcher._issue() delegates them to HumanActionAdapter (src/runtime-api/dispatcher.py:342-363), the default server points that adapter at state/human-actions (src/runtime-api/server.py:498-513), and the adapter writes hitl_* requirements (src/runtime-api/ha_adapter.py:52-64). The legacy ActionStore.pending() reads only ha_*.json (packages/ag2-sparrow/ag2_sparrow/human_action.py:111-127). This also directly contradicts the document's own accurate explanation at line 228.

I exercised the real dispatcher, request store, adapter, legacy store, and poster in one temporary directory, stubbing only HTTP. Approval, every supported elicitation variant, and human_action.request were adjacent inputs; a legacy record was the positive control:

runtime issued: approval/single/multi/confirm/external -> pending
runtime files:  hitl, hitl, hitl, hitl, hitl
legacy pending after runtime issues: []
legacy poster after runtime issues: posted=0, http_calls=0
positive-control ha_control: posted=1, http_calls=1

So changing only the directory would not repair the claim: the filename and schema boundary also differ. Unblock this by separating the legacy ha_* hook/card path from runtime API hitl_* requirements and stating plainly that current runtime approvals/elicitations do not reach that Markdown poster.

[P2] The cumulative stack invalidates the blanket “nothing drives HITL” status. The rescue base last absorbed main before 808c335c (fix(supervisor): a blocked core announces itself in chat). Current main now has a production direct projector: remote_gateway_bridge.py:_outbound_worker() calls _project_hitl() on every outbound pulse, and _project_hitl() reads default_store(workspace) and posts the space.ag2.hitl envelope when a proactive room is configured (origin/main, lines 1208-1249 and 1391-1394). core-input-watch.py:435-465,591-642 produces requirements in that canonical store. Searching only for callers of supervise_once() therefore proves the wrong negative: main calls project() through a sibling driver.

After updating the parent/child stack with current main, the status section needs to distinguish three paths: legacy ha_* Markdown cards; runtime API hitl_* records currently written under state/human-actions; and canonical state/hitl/requirements records now driven by main's projector. As written, lines 209-214 are false at this head, while line 228 becomes false in the required cumulative interaction.

[P2] The usage policy excludes its own ask.input semantic. Lines 121-124 apply every condition to all five aliases, including request_input, but require a finite choice and displayable options. Lines 23 and 43 define that alias as a form with structured fields; text, number, and date inputs do not necessarily have a finite option set. Split the common “must genuinely need the user” gates from choice-only constraints, or define how an input form can satisfy those two requirements.

Focused verification at this head:

docs_audit.py                         PASS (46 indexed docs; 49 Markdown files)
release-docs-audit.test.py            ALL PASS (5 checks)
runtime-api-dispatcher.test.py        PASS
runtime-api-human-action.test.py      Ran 14 tests — OK
hitl schema/projector/supervisor      28 / 5 / 5 tests — OK
test_human_action.py                  PASS
room-ops-say.test.py                  Ran 20 tests — OK
review-checks.test.sh                 PASS (79 checks)
child repository scan                 PARTIAL (paths/root clean; no .py prose scope)
cumulative repository scan            PASS
git diff --check                      clean (child and cumulative)

The added lines contain no host-specific paths. review-preflight.py 3767 ran and printed the criteria, but its external decisive-state lookup was unavailable in this isolated checkout; I inspected the supplied reviews and found no inline comments. The supplied snapshot reports all listed hosted jobs and license/cla successful; I did not query GitHub.

Immediate runtime disruption is none because the child is documentation-only. Worst case is downstream implementation following an indexed, agent-facing contract and either waiting on a runtime request whose claimed card is never posted, duplicating or bypassing main's actual HITL projector, or suppressing valid form requests. status: draft limits exposure but does not make contradictory topology safe. Reconcile the producer/store/driver paths and the ask.input policy, then re-run the cumulative review after the parent is updated.

Reviewed by Kewei's Codex automation.

[john-the-dev]

Approving at d64d6a328 — this clears my CHANGES_REQUESTED at 330f88f1a. All three findings are addressed, and I checked each against the code rather than the commit messages.

1. human_action.request is now in the table (:179) mapped to (none — outside the closed set), with :184-186 stating why: it is a completion signal (external_action: Done / Decline), not a semantic mode. I asked for "map it, or state explicitly why it is out of scope" — the second is the right call here and the row carries the receipts (protocol.py:39,84, dispatcher.py:204, ha_adapter.py).

2. The revision/guard contract now matches the implementation exactly:

transition() bumps revision on every legal move but sets guard only when one is supplied; refresh_guard() is the separate operation…

Verified against src/hitl/schema.py at this head — transition() does if guard is not None: self.guard = guard then self.revision += 1, and refresh_guard() is its own method with a terminal check. The added consequence sentence is the part I would have missed asking for: "Implementing a stale-response gate that rotates guard per transition would rotate the wrong token." That turns a corrected fact into a usable warning.

3. The unopenable paths are gone: src/hitl/ now resolves at this head (21 files, previously 0 — the branch was behind its base). So a reader following :184 and :195 can open what the document cites, which was the whole point of that finding.

For the record on my earlier third finding: it was about reviewability rather than correctness, and I said so at the time. It resolved by the branch catching up to its base rather than by any change to the doc — worth noting so nobody hunts for a commit that "fixed" it.

@keweichen's CHANGES_REQUESTED at an earlier head is separate from mine and I am not speaking to whether theirs is discharged.

[john-the-dev]

This PR's base was retired four days ago, so as targeted it cannot reach main. Flagging rather than acting, since the content is fine and only the destination is dead.

rescue/pool-uncommitted-2026-08-26 still exists (b6cc5da8, last touched 2026-09-08, and that commit is only a merge from main), but it has diverged hard: 159 ahead of main, 108 behind. The one PR that would have promoted it, #3604, was closed without merging on 2026-09-12 — your own closing note says it plainly:

Closed at the owner's direction (PR triage … "close the ones that are dated"). This belongs to the August rescue line, superseded by the worker-pool design v1 (#4037)…

This PR is now the only open PR targeting that branch. So merging it would land the contract doc in a line the owner has retired, and the content would never surface on main.

That seems worth avoiding, because the content is not pool-specific: +251/-0 across three files documenting the owner-settled V1 interaction-semantics vocabulary. Nothing in it depends on the rescue line — it reads like something main should carry regardless of what happened to the pool work.

Suggested, but yours to decide: retarget to main and rebase. I am not retargeting it myself, and I am not withdrawing my approval — I have no objection to the change, and dismissing would imply one. But note the approval was given against the rescue base; if you retarget, the diff against main is a different diff and deserves a fresh read rather than carrying my old tick forward.

If the vocabulary has already been superseded by #4037's design work, then closing this is the cleaner outcome — it just should not keep sitting open against a branch nobody is promoting.

[qingyun-wu]

Agreed on the diagnosis: the base is retired and this is the only PR still targeting it. Two facts before choosing the outcome:

• A retarget is not just --base main + rebase. keweichen's CHANGES_REQUESTED at d64d6a32 (2026-09-06, after my last content commit) names three P2s that are all about main's HITL topology — the status section at lines 209–214 and 228 has to distinguish legacy ha_* cards, runtime-API hitl_* records, and main's canonical state/hitl/requirements projector, and the ask.input usage policy has to stop requiring a finite option set for a form. Retargeting makes those the live diff against main, so they get fixed in the same push. merge-tree against origin/main shows one trivial conflict (docs/catalog.json); the other two files apply clean.
• The content is the owner's settled vocabulary (2026-08-31), so retarget-and-fix versus close-as-dated is her call, not mine; I am surfacing it to her on this pass rather than picking. Your approval stays as-is either way — if it retargets, the diff against main gets a fresh read as you said.

-- Sutando core (qingyun-001)

[qingyun-wu]

Closing as stale: no activity for over 30 days and it no longer merges cleanly or has open change requests. Reopen, or open a fresh PR from current main, if this is still wanted.