agent-wiki-summarize

# Agent Wiki — Summarize Trajectory

## Overview

Witness one session at a time. For each normalized trajectory JSON, author a
1–3 paragraph narrative + key turns + (when present) a classification of
each recalled guideline as `followed | ignored | contradicted` with an
evidence quote.

This is the per-trajectory **witness** pass of the `agent-wiki` family.
It writes one page per session and tail-calls the bookkeeping `catalog`
subcommand so indexes stay fresh.

## Input

A path that is either:

- a normalized trajectory JSON file
- a directory of such files (recurse one level into `<label>/items/`)

Default if no path is given:
`trajectories/normalized`.

## Workflow

### Step 1: Resolve input files

Use `Glob` to enumerate `*.json`. Accept either a single file, a flat dir
of files, or a `normalized/` root with `<label>/items/` subdirs.

### Step 2: Glance at existing summaries

`Glob wiki-twobatch/summaries/*.md` so you can skip-if-exists per session
without re-doing LLM work. Skip is the default; pass `--rewrite` (forwarded
to the helper below) to overwrite.

### Step 3: For each trajectory JSON

Read the file. The fields you need:

- `session_id`, `agent`, `model`, `started_at`/`ended_at`/`duration_seconds`
- `stats.top_tools` (for `tools_used`)
- `source.transcript_path`
- `openai_chat_completion.messages`
- `recalled_guidelines` (top-level; may be empty/missing)

If `wiki-twobatch/summaries/<session_id>.md` already exists and the
user did not request `--rewrite`, skip to the next file.

Otherwise synthesize a summary as a JSON object:

```json
{
  "session_id":      "<from JSON>",
  "slug":            "<optional; for splitting a long session into multiple arc-summaries (e.g. 'arc1-token-savings'). When present, filename becomes <sid>__<slug>.md and frontmatter gains `arc:` plus a `sibling_summaries:` list of co-summaries from the same session.>",
  "agent":           "<from JSON, default 'claude-code'>",
  "model":           "<from JSON>",
  "goal":            "<one short sentence describing what the user asked for>",
  "outcome":         "success | partial | failure",
  "duration_seconds": <number from JSON>,
  "tools_used":      ["<from stats.top_tools, name only>", "..."],
  "narrative":       "<1-3 paragraphs: what happened, what worked, what didn't>",
  "key_turns":       ["<one short bullet per pivotal step>", "..."],
  "normalized_path": "<path to the JSON, relative to repo root>",
  "transcript_path": "<from source.transcript_path>",
  "recalled_guidelines": [
    {
      "id":       "<12-hex-char id of the guideline that was used in this session>",
      "title":    "<a short label, 3-7 words>",
      "status":   "followed | ignored | harmful | contradicted",
      "evidence": "<verbatim quote ≤200 chars; required for followed/harmful/contradicted>"
    }
  ]
}
```

Rules of thumb:

- `goal` is one sentence; pull from the first user message.
- `outcome` is your judgement.
- `narrative` is short (≤ ~250 words). No fluff.
- `key_turns` is 3–6 bullets at most. Each one sentence.
- Skip `recalled_guidelines` entirely if no guidelines were available or used.
- Quotes must be verbatim (thinking / assistant text / tool_use args / tool_result content); ≤200 chars; ellipsize with `…` if cut.

### How `recalled_guidelines` is populated

The `recalled_guidelines` field captures **every wiki guideline the agent
saw in this session**. Scan the trajectory for the agent reading guideline
files from a wiki dir — `<wiki-root>/guidelines/<slug>__<gid>.md`
or `<wiki-root>/guidelines/<slug>__cluster.md` — either via the `Read`
tool or via Bash `cat`/`less`/`grep`. Extract each file's id from its YAML
frontmatter (`id: <12-hex>`) so the row links to the wiki's
`_id_index.json`.

Don't double-count: if the agent reads the same guideline file twice,
emit one row.

### Status vocabulary (4-way)

You judge the status from **trajectory evidence**, not the agent's
self-report:

- **`followed`** — the agent acted on the guideline and the action
  produced the intended result. Required `evidence`: a verbatim quote
  showing the agent applied the rule (citation, paraphrase that triggered
  a tool call, or a tool call whose form matches the guideline's
  prescription).
- **`ignored`** — the agent read the guideline file but never acted on
  it. No `evidence` needed; default for guidelines that landed in context
  without effect.
- **`harmful`** — the agent acted on the guideline and it led astray:
  wasted tool calls, wrong path, retracted decision, or surfaced a wrong
  answer that had to be corrected. Required `evidence`: a verbatim quote
  showing the bad outcome that followed application.
- **`contradicted`** — the agent saw the guideline and deliberately did
  the opposite (disagreed with the rule). Required `evidence`: a verbatim
  quote where the agent's action contradicts the guideline's prescription.

Default to `ignored` when uncertain. Don't assign `followed` or `harmful`
without a verbatim evidence quote — those carry signal value only when
backed by trajectory text.

### Step 4: Pipe the JSON to the helper

```bash
echo '<json>' | uv run python explorations/agent-wiki/skills/scripts/build_agent_wiki.py render-summary
```

Add `--rewrite` to overwrite an existing page. The helper:

- Locates the wiki root (existing `wiki-twobatch/` ancestor, or creates
  one next to the nearest `.git/` ancestor).
- Writes `summaries/<session_id>.md` with frontmatter, body, and a `## Sources` footer.
- Resolves each `recalled_guidelines[].id` against `guidelines/_id_index.json` for backlinks.
- Appends one `<wiki-root>/_audit.log` line per recalled guideline.
- Skips if the page already exists unless `--rewrite`.

### Step 5: Refresh indexes

After processing all input files, run **once**:

```bash
uv run python explorations/agent-wiki/skills/scripts/build_agent_wiki.py catalog
```

This regenerates `index.md`, section indexes, `_index.jsonl`, and enriches
summary frontmatter with `tool_calls`, `errors`, `re