5.6: .konveyor/ file contract (result.json, handoff.md)

[savitharaghunathan]

5.6: .konveyor/ file contract (result.json, handoff.md)

Part of Stream 5: Harness → AgentPlaybookRun alignment

ADR-0001 specifies a file contract between the harness, skills, and controller for communicating stage results and cross-stage context. The current harness uses a custom session.json format with pipeline-specific fields that doesn't match the ADR spec.

Tasks

• Define result.json schema — array of {"stage": "<name>", "status": "succeeded|failed", "reason": "<optional>"} entries
• Skills append their result entry to .konveyor/result.json after completion
• Harness reads final entry in result.json to determine exit code (0 = succeeded, 1 = failed)
• Harness commits .konveyor/handoff.md on exit — summary of what was accomplished and what remains (for the next stage's agent to read)
• Harness commits .konveyor/session.json on exit — session metadata (ADR-aligned format, not the old pipeline-status format)
• Playbook guide is committed as .konveyor/guide.md before stage 1 (by controller or harness)
• Controller reads result.json from completed pod to update AgentRun status
• Remove old internal/handoff/ package with pipeline-specific format

Acceptance Criteria

• Each skill writes a structured result entry to .konveyor/result.json
• Harness exit code reflects the skill's reported status
• .konveyor/handoff.md exists in the branch after each stage completes — the next stage's agent can read it for context
• .konveyor/guide.md exists before stage 1 when running as part of a playbook
• Controller can determine AgentRun success/failure from the pod's result.json

References

• ADR-0001 §Git-as-persistence steps 6–8
• ADR-0001 §AgentPlaybook execution model ("handoff files", "playbook guide")
• PR ✨ Harness init #33

[savitharaghunathan]

Update: file contract direction (2026-07-22)

Per discussion with @djzager: git commits are the primary cross-stage context. Don't create files unless there's a real consumer.

• results.json — the harness currently reads it to determine exit code, so it has a consumer today. But if the harness can determine success/failure another way (e.g., goose exit code, or checking whether expected artifacts like PLAN.md were written), results.json could become optional.
• handoff.md — should exist for cross-stage context only if git commits aren't enough for the next stage's agent. Don't over-engineer the schema until sub-agent work (Stage skill catalog and per-stage artifact contracts #54) surfaces a real need.
• session.json — dropped, no consumer exists.
• guide.md — replaced by KONVEYOR_PLAYBOOK_INSTRUCTIONS env var.

Also: issue body still says result.json (singular) — code and ADR 0006 now use results.json (plural).

[savitharaghunathan]

Update: results.json removed from harness (2026-07-22)

PR #53 now drops the results.json dependency entirely. The harness determines exit status from ACP completion signals (SendPrompt error or goose crash = failure, clean return = success). No skill-written status file is required.

Git commits are the primary cross-stage context. The eval stage (#59) will handle quality assessment. handoff.md remains as lightweight metadata (status, skills loaded, file counts) but is not load-bearing — if git commits prove sufficient, it can be simplified further.