Skip to content

docs(agents): document durable session-provenance files#47

Open
EricGrill wants to merge 2 commits into
nvk:masterfrom
EricGrill:fix/agents-md-session-provenance
Open

docs(agents): document durable session-provenance files#47
EricGrill wants to merge 2 commits into
nvk:masterfrom
EricGrill:fix/agents-md-session-provenance

Conversation

@EricGrill

Copy link
Copy Markdown

Fixes #35.

AGENTS.md only documented .research-session.json for --min-time runs, omitting the durable provenance files (.session-events.jsonl, .session-checkpoint.json) and .thesis-session.json. Portable agents following the single-file protocol therefore left behind incomplete provenance, which breaks /wiki:audit's ability to classify runs as replayable rather than partial.

What changed

Three minimal edits to AGENTS.md, all aligned with the canonical Claude source (claude-plugin/skills/wiki-manager/references/research-infrastructure.md and references/audit.md):

  1. Topic-wiki tree (around line 46) — adds .research-session.json, .thesis-session.json, .session-events.jsonl, .session-checkpoint.json with one-line comments distinguishing ephemeral from durable.

  2. "Session Registry" paragraph (around line 236) — replaced with a fuller "Session Files" block that covers:

    • Both ephemeral files and both durable files
    • Lifecycle (start / round / completion / interruption)
    • Resume protocol (active ephemeral first, then checkpoint + event-log tail)
    • Stale-session warning at >7 days
  3. Audit verdicts section — adds a one-line "Provenance classification" note documenting that audit reads the durable files to classify runs as replayable vs partial.

Verification

./tests/test-plugin-validate.sh   →  70 passed, 0 failed
./tests/test-structure.sh         →  92 passed, 0 failed
./tests/test-codex-sync.sh        →  Codex plugin mirror is in sync
./tests/test-opencode-sync.sh     →  OpenCode plugin mirror is in sync

Pre-flight checklist

  • Structural tests pass locally
  • No edits under `claude-plugin/skills/wiki-manager/` (sync scripts not needed)
  • No command additions/removals (no SKILL.md or README command-table update needed)
  • AGENTS.md is the only change, and it now matches the canonical Claude source
  • No new lint rules
  • No hand-edits in `plugins/llm-wiki/` or `plugins/llm-wiki-opencode/`

Notes for review

  • I deliberately mirrored the wording style already in AGENTS.md (dense paragraphs, bold lead-ins) rather than introducing a new format. Word count goes from 1 paragraph to 5, but each paragraph carries information that was missing.
  • Did not port the full JSON schemas from `research-infrastructure.md` — those belong in the deeper reference doc, not the portable single-file protocol. AGENTS.md just describes shape and lifecycle.
  • This PR is independent of docs(contrib): activate CI, add .github scaffolding, README Develop section #46 (CI activation + .github scaffolding). Either can merge first.

Hermes and others added 2 commits May 1, 2026 09:38
AGENTS.md only documented `.research-session.json` for `--min-time` runs,
omitting the `.session-events.jsonl` and `.session-checkpoint.json` durable
provenance files plus `.thesis-session.json`. Portable agents following the
single-file protocol therefore left behind incomplete provenance, which
breaks `/wiki:audit`'s ability to classify runs as `replayable` rather than
`partial`.

Three minimal edits, all aligned with claude-plugin/skills/wiki-manager/
references/research-infrastructure.md and references/audit.md:

- Topic-wiki tree (line 46) gains the four session files with one-line
  comments distinguishing ephemeral from durable.
- The "Session Registry" paragraph is replaced with a "Session Files"
  block that covers both ephemeral and durable files, the lifecycle
  table, and the resume protocol.
- Audit verdicts gain a "Provenance classification" line covering the
  replayable / partial distinction.

No plugin behavior change. All four structural tests pass
(70 + 92 assertions, both sync mirrors clean).

Closes nvk#35.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AGENTS.md is out of sync with the session-provenance file model

1 participant