forge-agent-report — the completion-report contract

Stops the Lead from hand-transcribing a dispatched Boss's final message into the dashboard. Every dispatched agent ends its final message with ONE fenced block; this skill's tool parses, validates, and ingests it.

Naming note: the tool lives at forge-bin/forge-report.cjs. The skill folder is named forge-agent-report (not forge-report) because skills/forge-report/SKILL.md already exists for a different thing — the Lead's own end-of-task delivery report format. Don't confuse the two: this skill is the per-agent machine-checkable contract; forge-report is the Lead's human-readable final report.

The contract (copy-paste into every dispatch prompt)

Include this requirement verbatim (or close to it) in every Agent(...) dispatch prompt (the outer fence has four backticks so the inner three-backtick block stays part of the text you copy):

End your final message with EXACTLY ONE fenced block:

```forge-report
{
  "status": "completed|partial|blocked|failed",
  "work_package": "WP-…",
  "files_changed": ["path/one", "path/two"],
  "tests_run": "the exact command(s) + result — or \"none\" if honestly nothing ran",
  "evidence": ["what actually proves this — command output, file diff, line count, etc."],
  "blockers": ["only if status is blocked — what's blocking you"],
  "next_action": "the single most useful next step",
  "verdict": "OPTIONAL, verifier reports only: PROVEN|PARTLY-PROVEN|NOT-PROVEN|NO-CONFIDENT-RESULT (a builder leaves this key out)"
}
```

If you emit more than one such block while thinking out loud, only the LAST one counts — make sure it
reflects your true final status.

When to use

• On every dispatch — the Lead includes the contract requirement above in the prompt of every Agent(...) call, named or not.
• On every return — when a dispatched agent's final message comes back, the Lead runs validate (or ingest directly) before treating the work as done. An agent claiming completed with no real evidence, or blocked with no blockers listed, is not a valid completion — send it back.

How to run

node .claude/forge-bin/forge-report.cjs validate <file|->
  # parse + validate a saved copy of the agent's message; exit 0 valid / 2 invalid

node .claude/forge-bin/forge-report.cjs ingest <run_id> <file|-> --agent "<Boss name>" [--root <projectRoot>]
  # parse + validate, then log ONE agent_output + ONE agent_evidence_added event into
  # <run>/events.jsonl (both already-registered VISIBLE-REASONING event types) — the dashboard
  # renders the report without the Lead re-typing anything. On an invalid report: logs NOTHING,
  # exit 2 — send it back to the agent instead.

<file|-> is either a saved file containing the agent's raw message, or - to read it from stdin.

Validation rules (the honesty gate)

• status must be one of completed | partial | blocked | failed.
• work_package must be a non-empty string.
• files_changed must be an array ([] is fine for a pure investigation).
• evidence must be an array, and when status is completed it must contain at least one non-empty string — a completed claim without evidence is rejected. This is the entire point of the gate: an agent cannot claim done without showing its work.
• blockers must be a non-empty array when status is blocked — a blocked claim with nothing listed as blocking it is rejected.
• tests_run must be a string or array — "none" is an honest, accepted answer; don't invent a test run that didn't happen.
• next_action must be a non-empty string.
• verdict is OPTIONAL and only for verifier reports (Verify Boss, forge-verify.cjs --claim): when present it must be exactly one of the four grades PROVEN | PARTLY-PROVEN | NOT-PROVEN | NO-CONFIDENT-RESULT (VERDICT_GRADES in forge-report.cjs), anything else is rejected. Only PROVEN counts as a pass; PARTLY-PROVEN and NO-CONFIDENT-RESULT are honest abstentions, never a pass. A builder report leaves the key out (details: .claude/skills/forge-verify/references/claim-verdict.md).
• Only the last ```forge-report block in the text is used (earlier ones may be drafts/examples from the agent's own reasoning).

Honesty rules

• The tool never logs anything on an invalid report — a rejected report goes back to the agent, not into the dashboard.
• The whole report is redacted with forge-bin/forge-store.cjs's redactValue() before it is embedded in any event — a secret accidentally pasted into evidence or tests_run never reaches events.jsonl in the clear.
• This tool only checks the shape of the claim (does it have real evidence listed, are blockers named, etc.) — it does not independently verify the evidence is true. Pair it with forge-verify for a task-state cross-check against events.jsonl.