fleet-trail-verification
How fleet-ops verifies audit trails during review — what to check, what constitutes a complete trail, and how to distinguish real work from paperwork
SKILL.md.claude/skills/fleet-trail-verification/SKILL.md
GitHubTrail Verification
Why This Matters
The trail is how the fleet proves work was done properly. Without trail verification, reviews become rubber stamps. A task with "code looks fine" is not reviewed — it's waved through.
The trail tells you: who did what, when, in what order, with what inputs. If the trail is incomplete, the review cannot be thorough.
What a Complete Trail Looks Like
Required Events (all task types)
- Task created — who created it, with what fields
- Task accepted — agent accepted with a plan
- Progress updates — readiness changes with explanations
- Commits — conventional format, linked to task
- Task completed — summary of what was done
Required Events (stories and above)
- Contributions received — design_input, qa_test_definition, security_requirement
- Contributions consumed — evidence that inputs were used (referenced in plan, commits)
- Readiness gates — 50% checkpoint, 90% gate request
Required Events (review tasks)
- Review started — reviewer acknowledged the task
- Review criteria checked — each criterion evaluated
- Decision recorded — approved/rejected with specific reasoning
How to Verify
Step 1: Reconstruct
Use the trail-reconstructor sub-agent:
Launch trail-reconstructor with task_id
This returns a chronological event list without bloating your context.
Step 2: Check Completeness
Against the checklist above. Mark each event as:
- PRESENT — event exists in trail
- MISSING — event should exist but doesn't
- SUSPICIOUS — event exists but timing or content is unusual
Step 3: Check Authenticity
- Timing: Are events in logical order? (Can't have commits before acceptance)
- Content: Do commit messages match the plan? Do progress updates describe real work?
- Contributions: Did the agent actually reference contributions in their work? (Check commit diffs — does the code follow architect's design input?)
- Stage compliance: Did the task move through stages in order? (conversation → analysis → investigation → reasoning → work)
Step 4: Assess Quality
A complete trail with garbage content is still a bad trail:
| Quality Signal | Good | Bad |
|---|---|---|
| Plan | References verbatim, maps to contributions | "Will implement the feature" |
| Progress | Specific: "auth middleware done, JWT signing with RS256" | "Making progress" |
| Commits | Conventional format, meaningful messages | "WIP", "fix", "update" |
| Completion | Explains what, why, how to verify | "Done" |
Trail Gaps That Block Approval
These gaps mean you CANNOT approve:
- No plan accepted — agent skipped planning
- No contributions — agent worked without required inputs
- No tests — engineer skipped verification
- No commit trail — no evidence of incremental work
- Stage jumps — task went from conversation to work (skipped analysis/investigation)
Trail Gaps That Warn But Don't Block
These gaps warrant a note but not rejection:
- Missing 50% checkpoint — informational, not structural
- Sparse progress updates — preference, not requirement
- Contribution tasks exist but trail event not recorded — check if contribution actually exists in task context
The Distinction: Real Work vs Paperwork
A trail exists to prove real work happened. If you find yourself checking boxes without examining content, you're doing paperwork, not verification.
Real verification: "The plan references architect's design for repository pattern. The commits show a RepositoryBase class. The test files test the repository. The security contribution said 'validate inputs at boundary' — the commit adds input validation at the API layer."
Paperwork: "Plan exists. Commits exist. Tests exist. Approved."
Group Call
ops_real_review(task_id, trail_data, criteria)
The review group call includes trail verification as step 3 of the 10-step review protocol.