Evidence layer / Agent logging

Give the team a flight recorder.

Artifacts show what the pipeline produced. The agent log records how it got there: decisions, alternatives, findings, struggles, assumptions, and whether expected outcomes actually happened.

Agent log

structured evidence across otherwise stateless sessions

Interactive record anatomy

What kind of signal happened?

Inspect

runs table

Session envelope

Links one specialist session to an agent, feature, status, quality score, and output summary.

Agent decides: How to summarize the work and score its quality
Code enforces: UUID, required fields, timestamps, and persistence

Start a run

RUN_ID=$(bin/agent-log run start \
  --agent-name engineer \
  --feature-id 001 \
  --input-summary "Build sync status")

01 / Two evidence systems

Artifacts and logs answer different questions.

You need both. Collapsing them either bloats the handoff documents or leaves the learning layer unable to see why an apparently successful result happened.

Feature artifacts

What exists now?

Approved problem and requirements
Architecture and design commitments
Implementation and review reports
Canonical feature summary

docs/briefs/001-feature/

Agent log

What did the system learn?

Choices and rejected alternatives
Expected versus observed outcomes
Repeated review categories
Struggles, assumptions, and skill gaps

db/agent_log.sqlite3

Boundary

The Markdown artifacts are the pipeline API. The database is the longitudinal evidence layer. A future agent may read both, but neither replaces the other.

02 / Lifecycle protocol

Every agent run opens and closes an evidence envelope.

The shared logging skill owns the lifecycle. Each agent definition supplies only role-specific criteria: what counts as a meaningful decision, finding, or gap.

01
First action
Start run
Create the UUID that correlates every record in this session.
run start
02
During judgment
Record signal
Log material decisions, meaningful events, and review findings—not narration.
decision · event · finding
03
Before artifact
Surface assumptions
Query reflections so gaps become visible in the agent’s report.
query reflections
04
Before close
Reflect
Name genuine struggles and targeted skill gaps when they occurred.
reflection
05
Last action
End run
Persist status, quality score, and a concise output summary.
run end
06
After delivery
Record outcome
Compare an earlier expected result with what actually happened.
outcome

03 / Five-table data model

Store claims at the level you will analyze.

A generic event stream is easy to write and hard to learn from. Typed records preserve the distinctions the analyst needs later.

runs

Session identity

Agent, feature, input mode, status, quality score, timing, output summary.

one row / specialist session

decisions

Reasoned choices

Title, rationale, alternatives, type, expected outcome, observed outcome.

hypothesis → result

events

Meaningful actions

Test runs, significant commands, and artifacts written.

test_run · bash · file_write

findings

Review evidence

Stable category, severity, file, line, and description.

AUTH_SCOPE · N+1 · MISSING_TEST

reflections

Capability gaps

Assumptions, struggles, and specific missing knowledge.

assumption · struggle · skill_gap

04 / Signal discipline

Log decisions, not exhaust.

The database becomes useful only when each row carries analytical signal. More telemetry is not automatically more observability.

Log this

Choosing between two valid approaches
Deviating from the approved plan
Resolving an ambiguity without the user
A test run or significant command
A reviewer’s categorized finding
An upstream artifact gap
A specific skill the agent lacked

Skip this

Every file the agent reads
Obvious single-path implementation steps
Chain-of-thought or private reasoning
Routine narration of progress
Duplicate facts already in an artifact
Unstructured “something felt hard” notes
Metrics no decision will ever use

“If no future decision can use the record, it is noise.”

05 / The silent failure mode

Every worktree must write to one shared recorder.

A relative database path creates one database per worktree. Those records disappear from analysis when the worktree is removed.

Main checkout

Canonical evidence

/project/db/agent_log.sqlite3

All features and agents accumulate here.

AGENT_LOG_DB

Feature worktree

Agent execution

/001-sync-status/

Every launch receives the absolute shared path.

Required launch preamble

cd {WORKTREE_DIR}
export AGENT_LOG_DB={PROJECT_ROOT}/db/agent_log.sqlite3

Failure policy

Logging failure should not destroy feature work. Continue the task, surface the evidence gap in the final artifact, and never pretend the record exists.

06 / Questions the data can answer

Design the recorder backward from decisions.

These are the queries that justify the system. If your schema cannot answer them, you are collecting activity rather than learning evidence.

Recurrence

Which decisions keep being made?

GROUP BY title HAVING COUNT(*) > 1

Prevention

Which findings repeat across features?

COUNT(DISTINCT feature_id)

Prediction

Where did expected and observed diverge?

expected_outcome ≠ observed_outcome

Upstream quality

Which artifact keeps forcing assumptions?

decision_type = 'gap'

Capability

What knowledge do agents repeatedly lack?

reflection.type = 'skill_gap'

Correlation

Which practices accompany strong runs?

quality_score ≥ 8

07 / Portable implementation

Keep the tool deterministic and the meaning interpretive.

The CLI validates fields, assigns IDs, timestamps rows, and persists transactions. Agents decide which moments are meaningful and write concise rationales. The analyst later interprets patterns across runs.

Read the source documentation

Code must guarantee

Stable schema and vocabulary
Run/record correlation
Required fields and timestamps
Atomic writes and explicit path
Read-only analytical queries

AI must supply

Materiality judgment
Rationale and alternatives
Expected outcome
Gap and struggle descriptions
Observed outcome interpretation