run-log

name	run-log
description	Write the run-log entry that records what this run did. Use at the end of every agent run, scheduled or manual, before committing.
audience	team

Writing your run log

Every run leaves one record. The cockpit reads these, and so does the person who was asleep while you worked.

1. Collect the facts

node scripts/run-facts.mjs <agent> [workflow]

One command, every fact below, and the path to write to. It runs the same in PowerShell, Terminal and bash, so it does not matter which machine you are on.

started_at   2026-08-30T14:27:44Z
trigger      manual
session_id   null
session_url  null
run_id       2026-08-30T1427Z-research-morning-intel
path         runs/2026-08/2026-08-30T1427Z-research-morning-intel.json

• session_id is CLAUDE_CODE_REMOTE_SESSION_ID. On a local run it is empty and the command prints null; write null.
• trigger reads CLAUDE_CODE_REMOTE. The command prints schedule for every remote run — if a webhook fired this one rather than the clock, write webhook instead.
• finished_at is the same command run again once the work is done.

2. Write the file

Path: runs/<YYYY-MM>/<run_id>.json, where run_id is <YYYY-MM-DD>T<HHMM>Z-<agent>. If the run executed a workflow, append its slug — <...>Z-<agent>-<workflow> — so two jobs owned by one agent in the same minute never collide. No colon anywhere in the name — these files are read on Windows. Step 1 builds this name for you and prints it as path, colon-free and with the workflow slug already appended.

If this run executed a workflow (a file in workflows/), record which one in a workflow field — its slug, exactly as the filename. The dashboard's Workflows board matches runs to workflows through this field; without it your workflow shows "never run" forever, no matter how often it runs. A run that was not a workflow omits the field.

{
  "schema": "run-log/v1",
  "run_id": "2026-08-07T0600Z-research-morning-intel",
  "agent": "research",
  "workflow": "morning-intel",
  "model": "sonnet",
  "trigger": "schedule",
  "started_at": "2026-08-07T06:00:12Z",
  "finished_at": "2026-08-07T06:04:38Z",
  "status": "ok",
  "summary": "Complete sentences, written for someone who saw none of this. Open with what happened.",
  "artifacts": ["agents/research/output/2026-08-07-competitor-pricing.md"],
  "evidence": ["WebSearch returned 11 results", "Wrote 1 file"],
   
   
   

If the run was graded

A run whose output went through review-draft adds one more block. The weekly quality review counts acceptance from these, so a grade you do not record is a grade that never happened.

"quality": {
  "rubric": "content",
  "score": 11,
  "total": 12,
  "verdict": "passed",
  "retried": false
}

verdict is passed or flagged - the grader's call. It is not the owner's call; that arrives later as a verdict in quality/verdicts/, and the two disagreeing is the most useful signal the review produces.

Field meanings are in runs/README.md.

3. Choose an honest status

Status	When
ok	The task finished and you can point to the output
partial	Some of it finished; say which part did not, in summary
blocked	Something outside your control stopped you — a missing connector, an empty brain
failed	It broke. Put the error in evidence.

evidence holds things a tool returned. If you cannot point at a tool result for a claim, leave the claim out.

4. Check it

node scripts/validate-run-log.mjs runs/2026-08/2026-08-07T0600Z-research.json

Fix anything it reports, then run it again.

It refuses a field the schema does not have, rather than dropping it in silence, and for the names people reach for it says which one you meant - session_link for session_url, output for artifacts, next_steps for next_action. Do not invent a field to carry extra detail: nothing reads it, so the detail is lost, and summary and evidence are where detail belongs.

5. Commit the artifact and the log together

git add agents/research/output/2026-08-07-competitor-pricing.md runs/2026-08/2026-08-07T0600Z-research.json
git commit -m "research: competitor pricing sweep for 2026-08-07"

The artifact and the run log go in the same commit. A log with no artifact and an artifact with no log are both half-records, and the cockpit shows the gap.

If you were told not to commit, do not commit. Leave both uncommitted and say so. The rule is that the two move together — not that a commit always happens. An agent that commits over an instruction not to has broken something worse than a half-record.