upward-report · diff
git:20261103.92630ca to git:20261105.cdc6974
47 added, 36 removed. Audit A to A.
---
name: upward-report
- description: Mandatory output contract for warden agents. Warden agents append a YAML upward-report block as the last content of their response. Parent (main thread) parses and routes via dispatcher FSM. Use when you are a warden agent finishing a task, OR when you are the parent consuming a warden's output.
+ description: Mandatory closing block for every warden response, and the input the parent routes on. Use when you are a warden finishing (or stopping) a mission, or when you are the parent reading a warden's result. The wardens SubagentStop hook checks it, and `bun run repo warden-report` validates it and names the next action.
---
- # UpwardReport
+ # UpwardReport — truth out
- Mandatory structured output for warden agents during the team-ownership pilot. Mirrors A2A `TaskState` per [[2026-05-18-agentic-team-ownership-concepts]] §gap-2.
+ > **Vendored** from [tylerjrbuell/wardens](https://github.com/tylerjrbuell/wardens) `skills/upward-report/SKILL.md` (contract v2) so non-Claude agents see the same contract. `bun run repo warden-report` (`tools/repo/src/commands/warden-report.ts`) implements the same rules. Edit upstream first, then re-sync both. History: [[2026-09-03-warden-pilot-ratified]].
- ## Format (append as LAST content in warden response)
+ The warden owns the outcome, including a bad one. The report says what happened in a form the parent can route on without having to interpret it. Make it the **last content** of the response.
+ ## In this repo
+
+ - Before reporting `completed`, run `bun run repo verify <pkg-dir>` and put the result under `verification`.
+ - Self-check before you send: `bun run repo warden-report -`. The parent runs the same command and follows its `next:` line.
+
+ ## Format
+
```yaml
upward-report:
- status: completed | failed | blocked | denied-by-authority
+ status: completed | failed | blocked | denied-by-authority | needs-approval
confidence: 0.0-1.0
- blockers:
- - <concrete: file:line | error string | missing dep>
- escalation-required: true | false
- escalation-reason: <if true>
- evidence-anchors:
- - <file:line | command-output | test-id>
- planned-actions-pending-approval:
- - <if high-impact action queued but not yet executed — Marquet "I intend to..." pattern>
+ files-changed:
+ - <path>
+ verification: # commands YOU ran this session, with their result
+ - "<command> → <result>"
+ evidence-anchors: # where the parent can check your claims
+ - <file:line | test id | command output excerpt>
+ blockers: # concrete: file:line, error string, missing dependency, out-of-scope path
+ - <blocker>
+ planned-actions: # needs-approval only: "I intend to …" (legacy name planned-actions-pending-approval still accepted)
+ - <action>
+ escalation-required: false
+ escalation-reason: <required when escalation-required is true>
notes: <one line, optional>
```
- Validate before sending or routing: `bun run repo warden-report <file|->` checks the block and prints `next:` per the FSM below. Run `bun run repo verify <pkg-dir>` before reporting `completed`.
-
- ## Field rules
+ ## Status: pick exactly one
- - **status `completed`** + `confidence < 0.7` → parent runs verifier (deterministic gates), does NOT re-prompt warden for self-review.
- - **status `failed`** + non-empty `blockers` + `retries-allowed > 0` (from MissionBrief) → parent re-dispatches with blockers injected into next brief.
- - **status `failed`** + retries exhausted OR `escalation-required: true` → parent escalates via `AskUserQuestion`. NEVER silent retry past retry budget.
- - **status `denied-by-authority`** → parent escalates. Cannot re-plan around an authority bound; widening = user decision.
- - **planned-actions-pending-approval** non-empty → parent gates before warden executes; high-impact actions ("delete file X", "rename API Y across N callers") require this.
+ | Status | Meaning | Required | `warden-report` next |
+ |---|---|---|---|
+ | `completed` | End-state met, inside authority | `verification` if confidence ≥ 0.7 | `verify` (≥ 0.7) / `verify-with-ablation` (< 0.7) |
+ | `failed` | Tried, end-state not met, and you know why | `blockers` | `redispatch` (retries left) / `escalate` |
+ | `blocked` | Something outside any warden's reach: credentials, broken infra, a decision only a human can make | `blockers` | `surface-blocker` |
+ | `denied-by-authority` | The work needs a path or command outside your authority (or the guard denied one) | `blockers` naming the path/command | `reroute` to the owner (`escalate` if escalation-required) |
+ | `needs-approval` | You have a plan, and part of it is high-impact (delete, cross-caller rename, schema/API change). You stopped before doing it | `planned-actions` | `gate` |
- ## Dispatcher FSM (parent thread behavior)
+ ## Confidence is tied to evidence
- | Report state | Parent action |
+ | Confidence | Means |
|---|---|
- | `completed`, confidence ≥ 0.7 | Run verifier (typecheck + targeted tests). Pass → accept. |
- | `completed`, confidence < 0.7 | Run verifier + ablation-warden if change is a new mechanism. NEVER re-prompt warden for self-review (M3 REWORK precedent). |
- | `failed`, blockers present, retries remain | Re-dispatch with blockers in MissionBrief.key-tasks |
- | `failed`, retries exhausted OR escalation-required | Escalate via AskUserQuestion. |
- | `denied-by-authority` | Escalate. Authority widening is user-only. |
- | `blocked` | Surface blocker to user; do not re-dispatch. |
+ | ≥ 0.9 | Every success criterion verified by a command you ran; no known open edge |
+ | 0.7 – 0.9 | Verified, but there's a known untested edge or the mechanism is new |
+ | 0.4 – 0.7 | Partially verified |
+ | < 0.4 | Not verified |
- ## Anti-pattern (refuse these)
+ Confidence ≥ 0.7 with an empty `verification` is invalid. If you don't have the evidence, don't claim the confidence.
- - ❌ Parent runs another LLM call to "review" warden's output → recreates verifier.ts:217-222 double-rejection failure and M3 verify-retry loop.
- - ❌ Silent retry past `retries-allowed`.
- - ❌ Authority widening without user gate.
- - ❌ Accepting `completed` + `confidence < 0.7` without running deterministic verifier.
+ ## Rules for the warden
- ## Status
+ - **Own it.** No "the model was flaky" or "pre-existing issue" without an anchor that proves it, such as a stash-and-rerun baseline.
+ - **Don't work around the guard.** A denied tool call means your report is `denied-by-authority`. Don't try another route to the same edit.
+ - **Don't commit, push, tag, or publish.** Integration belongs to the parent.
+ - **Report surprises in `notes`.** They feed the debrief.
- Ratified as permanent. See [[2026-09-03-warden-pilot-ratified]].
+ ## For the parent
+
+ Follow the `next:` line from `bun run repo warden-report`. Never answer a report by asking the same warden to "double-check its work": that recreates the `verifier.ts:217-222` double-rejection failure and the M3 verify-retry loop. Re-run the deterministic gates yourself.