Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,38 @@ versioning; the release tag, the package `version`, and this file are kept in lo

## [Unreleased]

### `advisor-board --reply-format json`: a machine-consumable, verified reply per seat

- **What it does.** `phase-loop advisor-board <artifact> --reply-format json` asks every seat for ONE
JSON object (`verdict`, `summary`, `findings[]` with `severity`, `title`, `body`, optional
`location`) followed by the usual last line (the verdict word), and verifies the reply with the
strict `panel_reply` verifier that shipped in 0.7.25 and nothing called until now. A reply that
verifies is attached to the seat (`PanelLegResult.panel_reply`) and appears under `reply` in
`--json` and in the per-seat streamed verdict file. A reply that does not verify is DEGRADED with a
typed `panel_reply_<kind>` detail (`no_json`, `ambiguous_reply`, `schema_mismatch`,
`verdict_missing`, `verdict_forbidden`, `verdict_inconsistent`, `terminal_mismatch`,
`recommendation_missing`, `too_large`) and its text kept, so the governed classifier holds it like
any non-conforming review. `--json` gains a top-level `reply_format` and a per-seat `reply`, only
when the flag is used; every other payload is unchanged.
- **The JSON is followed by the legacy last line, on purpose.** Every seat transport already decides
that a reply is complete from its last line, so nothing in the transports changes. The verifier
requires that line to agree with the JSON (`terminal_mismatch` otherwise): a seat cannot satisfy the
transport with one verdict and the consumer with another.
- **How the format reaches the seats.** The brief is bound by the HARDEN instruction digest and by
the sealed prompt envelope, and about ten call sites resolve it independently, so the runtime does
not append to a seat's prompt. The CLI extends the review brief itself (review brief plus the
format instructions, rendered from the same model that verifies), stages it as one file, and passes
it as `brief_ref` everywhere, with the digest minted from exactly those bytes: the mechanism the
advisory contract already uses. A `--native-leg` fill must be prepared with the same flag; it is
verified like any seat.
- **Refused combinations.** `--advisory` (an advisory review is recognised by the exact digest of its
contract, so extending that brief could make a non-landing review stop looking like one) and agy
canary capture (it records the exact default brief). Both are refused before any probe.
- **Python callers.** `invoke_board(..., reply_format="json")` verifies each seat's reply as it
lands, before any `on_leg_complete` callback sees it, and again after native fills are bound; the
caller's own brief must already ask for the format. The default (`None`) is byte for byte the
previous behaviour, and `_default_spawn`'s call signature is unchanged.

### The execution driver for non-local placement, built and not turned on (agent-harness#896)

- New: the driver that decides where a review seat may run and launches it on a remote
Expand Down
21 changes: 21 additions & 0 deletions docs/advisor-board-capabilities-card.md
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,27 @@ after network entry and before capability removal, so cancellation ownership
does not restore the provider's ability to change its firewall. Missing required
egress remains a DEGRADED leg with the exception detail, never an isolation claim.

## Machine-consumable replies (`--reply-format json`)

`phase-loop advisor-board <artifact> --reply-format json` asks each seat for one JSON object, then
its usual last line, and verifies it.
- **The reply.** `{"verdict": "AGREE" | "PARTIALLY AGREE" | "DISAGREE", "summary": "...",
"findings": [{"severity": "blocking" | "non_blocking", "title": "...", "body": "...",
"location": "..."}]}`, then the verdict word on the last line. `DISAGREE` needs a blocking
finding, `AGREE` allows none, `PARTIALLY AGREE` needs a finding. No extra fields, no coercion, and
exactly one JSON object.
- **A verified reply** is under `reply` for that seat in `--json` (and in its streamed
`leg-*.verdict.json`). **One that does not verify** is `DEGRADED` with `detail` of
`panel_reply_<kind>` and its text kept, so a governed run holds it as a non-conforming review.
Kinds: `no_json`, `ambiguous_reply`, `schema_mismatch`, `verdict_missing`, `verdict_forbidden`,
`verdict_inconsistent`, `terminal_mismatch` (the last line is not the JSON's verdict),
`recommendation_missing` (advisory boards), `too_large`.
- **The brief.** The CLI extends the review brief with the format and stages it as the one brief
file every seat and every native fill binds; a `--native-leg` fill must be prepared with the same
flag. `--advisory` and agy canary capture are refused with it.
- **Output.** `--json` has a top-level `reply_format` and a per-seat `reply` only when the flag is
used. Without the flag nothing about a run changes.

## Session names for Claude seats

A Claude panel seat appears in the Claude app's session list as `<repo> · <mode> · [<topic> ·]
Expand Down
52 changes: 49 additions & 3 deletions phase-loop-runtime/src/phase_loop_runtime/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -1156,6 +1156,14 @@ def build_parser() -> argparse.ArgumentParser:
help="Path to the review material staged into the board bundle.",
)
advisor_board_sub.add_argument("--json", action="store_true", help="Emit the board verdicts as JSON.", default=argparse.SUPPRESS)
advisor_board_sub.add_argument(
"--reply-format", dest="reply_format", choices=("json",), default=None,
help=("Ask every seat for a machine-consumable reply: ONE JSON object (verdict, summary, findings[]) "
"then the usual last line, and verify it. A reply that does not verify is DEGRADED with a typed "
"panel_reply_<kind> detail and held like a non-conforming review; a verified one is under "
"`reply` in --json. The brief is extended with the format, so a --native-leg fill must be "
"prepared with the same flag. Not combinable with --advisory or agy canary capture."),
)
# REVIEWTRUTH early slice (EC-REVIEWTRUTH-14): the native-fill protocol under Claude Code.
advisor_board_sub.add_argument(
"--emit-native-request", dest="emit_native_request", action="store_true", default=False,
Expand Down Expand Up @@ -2073,7 +2081,9 @@ def _review_isolation_hint(exc: BaseException) -> str | None:
return None


def _advisor_board_command(*, args: argparse.Namespace, _advisory_root: Path | None = None) -> int:
def _advisor_board_command(
*, args: argparse.Namespace, _advisory_root: Path | None = None, _reply_root: Path | None = None,
) -> int:
"""LEGACY (CLEANSHIP P7): run the 4-vendor advisor board as the RUNNABLE
agent-facing default. Composes availability-aware seats via
``compose_review_board`` (REVIEWGOV IF-0-REVIEWGOV-1: ``is_available ∧ auth_ok``,
Expand Down Expand Up @@ -2117,6 +2127,18 @@ def _advisor_board_command(*, args: argparse.Namespace, _advisory_root: Path | N
finally:
os.environ.update(removed_git)

reply_format = getattr(args, "reply_format", None)
if reply_format is not None:
if advisory:
# An advisory run is recognised by the exact digest of its contract; extending the
# brief would change that digest and a non-landing review could stop looking like one.
print("advisor-board: --reply-format cannot be combined with --advisory (the advisory "
"contract is recognised by its exact bytes)", file=sys.stderr)
return 2
if _reply_root is None:
with tempfile.TemporaryDirectory(prefix="advisor-board-reply-format-") as reply_root:
return _advisor_board_command(args=args, _advisory_root=_advisory_root, _reply_root=Path(reply_root))

from .advisor_board.backing import (
clear_review_composition_authorization,
prepare_review_composition_authorization,
Expand Down Expand Up @@ -2148,6 +2170,18 @@ def _advisor_board_command(*, args: argparse.Namespace, _advisory_root: Path | N
advisory_brief_path = _advisory_root / "advisory-contract.md"
advisory_brief_path.write_text(ADVISORY_CONTRACT, encoding="utf-8")
advisory_brief_ref = str(advisory_brief_path)
if reply_format is not None:
# The brief is bound by the HARDEN instruction digest and the sealed prompt envelope, and
# about ten call sites resolve it independently, so the format instructions are made part
# of the brief itself: one file, passed as `brief_ref` everywhere (the same mechanism the
# advisory contract uses), and the digest minted from exactly these bytes.
from .panel_reply import render_reply_instructions

assert _reply_root is not None
review_brief = review_brief.rstrip("\n") + "\n\n" + render_reply_instructions("review")
reply_brief_path = _reply_root / "review-brief-reply-format.md"
reply_brief_path.write_text(review_brief, encoding="utf-8")
advisory_brief_ref = str(reply_brief_path)
monitoring_policy = getattr(args, "monitoring_policy", "bounded")
try:
resolve_review_monitoring_policy(
Expand Down Expand Up @@ -2203,6 +2237,11 @@ def _advisor_board_command(*, args: argparse.Namespace, _advisory_root: Path | N
print("advisor-board: capture is a governed exact-four run and cannot be --advisory", file=sys.stderr)
capture.close()
return 2
if capture is not None and reply_format is not None:
print("advisor-board: capture records the exact default brief and cannot be --reply-format",
file=sys.stderr)
capture.close()
return 2
review_authorization = None
instruction_token: object | None = None
canonical_repo_authority: Path | None = None
Expand Down Expand Up @@ -2262,7 +2301,7 @@ def _advisor_board_command(*, args: argparse.Namespace, _advisory_root: Path | N
try:
artifact_text = artifact_path.read_text(encoding="utf-8")
payload = native_fill_request_payload(
board, artifact_text, **({"brief_ref": advisory_brief_ref} if advisory else {}),
board, artifact_text, **({"brief_ref": advisory_brief_ref} if advisory_brief_ref is not None else {}),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve reply format in native-fill resume output

When --emit-native-request --reply-format json is used, this binds the request to the extended structured-reply brief, but the early-return JSON record does not include reply_format and the printed re-run command omits --reply-format json. Following that generated command reconstructs the ordinary brief, so preflight_native_leg_fills rejects the completed fill with a brief-digest mismatch before any seat launches. Include the reply format in both the record and suggested resume command.

Useful? React with 👍 / 👎.

)
root = Path(getattr(args, "native_fill_dir", None) or artifact_path.resolve().parent)
out_dir = root / "native-fill" / str(payload["request_id"])
Expand Down Expand Up @@ -2394,7 +2433,7 @@ def _on_seat_modes(modes) -> None:
"artifact_ref": str(artifact_path.resolve()),
"repo_dir": scratch,
**({"native_leg_fills": native_leg_fills} if native_leg_fills else {}),
**({"brief_ref": advisory_brief_ref} if advisory else {}),
**({"brief_ref": advisory_brief_ref} if advisory_brief_ref is not None else {}),
"agy_canary_capture": capture,
**({"monitoring_policy": monitoring_policy} if monitoring_policy != "bounded" else {}),
"on_seat_modes": _on_seat_modes,
Expand All @@ -2407,6 +2446,8 @@ def _on_seat_modes(modes) -> None:
invoke_kwargs["review_authorization"] = review_authorization
invoke_kwargs["canonical_repo_authority"] = canonical_repo_authority
invoke_kwargs.update(president_kwargs)
if reply_format is not None:
invoke_kwargs["reply_format"] = reply_format
result = invoke_board(board, artifact_text or "", **invoke_kwargs)
except PresidentPolicyError as exc:
# PRESROUTE: a refused president path (override, stream, resume) is a typed exit.
Expand Down Expand Up @@ -2536,10 +2577,15 @@ def _on_seat_modes(modes) -> None:
# notice, provider terminal state); absent under the bounded policy.
**({"review_monitoring": dict(leg.review_monitoring)}
if leg.review_monitoring is not None else {}),
# --reply-format json: the seat's verified structured reply; absent otherwise.
**({"reply": leg.panel_reply.model_dump(mode="json")}
if leg.panel_reply is not None else {}),
}
for leg in result.legs
],
}
if reply_format is not None:
payload["reply_format"] = reply_format
if pointer_brief:
# agent-harness#1204: present only for a pointer-brief board, so every other
# payload (and the closed capture schema) is unchanged.
Expand Down
Loading
Loading