Trajectory Risk Supervisor

Purpose

Use observable task traces to detect quality drift before finalization without turning the harness into a blocking daemon.

Inspect First

• docs/observability/task-trace.jsonl
• docs/observability/trajectory-risk-policy.json
• docs/observability/trajectory-risk-report.md
• feature state, sprint contract, termination evidence, pre-edit evidence, review findings, and recent validation output

Procedure

1. Collect or inspect trace events.

   • Use docs/observability/task-trace.jsonl as newline-delimited JSON.
   • Events should record task id, task type, phase, action, files read, files changed, commands run, validation, risk surfaces, intervention, outcome, and notes.
   • Use scripts/append_task_trace.py when a deterministic event append is useful.

2. Classify the current trajectory.

   • Run scripts/classify_agent_trace.py <repo> --json.
   • Derive task phase, task type, repo understanding, diff scope, test status, risk surfaces, repeated failure loops, and evidence coverage.

3. Check invariants and score risk.

   • Run scripts/check_trajectory_invariants.py <repo> --json.
   • Run scripts/score_trajectory_risk.py <repo> --json.
   • Treat scoring as shadow/advisory unless the target repo explicitly wires enforcement through its own wrapper.

4. Recommend the least disruptive intervention.

   • Editing before inspection routes to $pre-edit-investigation-gate.
   • Repeated failures route to $agent-failure-introspection.
   • Finalization without tests routes to $termination-gatekeeper.
   • Dependency choices without sources route to $research-first-change.
   • UI lifecycle gaps route to $click-path-and-browser-qa.
   • Security, migration, or broad-diff risks route to $agent-reviewer or a generated reviewer subagent.

5. Document risk when useful.

   • Use assets/templates/trajectory-risk-report.md.tmpl.
   • Keep hooks out of default behavior; plugin hooks are a future opt-in shadow layer only after users trust them.

Validation

• Run scripts/classify_agent_trace.py <repo> --json.
• Run scripts/score_trajectory_risk.py <repo> --json.
• Confirm every risk cites trace evidence and maps to a concrete intervention or command.
• Confirm advisory mode does not block unrelated lightweight repos.

Completion Criteria

• The current task trajectory has a clear state, risk level, evidence list, and recommended intervention.
• The repo can opt into ./scripts/check-trajectory-risk without changing the stable baseline command interface.