mastermind-structured-report-contract

Structured report contract

The only canonical machine-consumed agent handoff is <task>/executor-report.md. The Rust controller reads that file, extracts its sentinel-wrapped YAML, validates schema v1, and uses its supported claims and verification observations during post-flight.

A copy returned in chat is useful to humans but is not the lifecycle record. The controller does not scrape planner chat, automatically patch a spec, or re-spawn an executor. Missing or malformed file evidence fails post-flight.

Executor tail

Append this tail to the prose report in executor-report.md:

<!-- mastermind:report-begin -->
```yaml
schema_version: 1
spec: .mastermind/tasks/<NNN>-<name>/spec.md
status: complete | partial | failed
phases:
  - id: plan-1
    status: done          # done | pending | stopped_here | skipped
files_modified:
  - path/relative/to/repository
claims:
  - kind: function_added
    symbol: <new symbol>
    file: path/to/file
    signature: "<indexed signature when available>"
  - kind: integration
    from: <changed caller>
    from_file: path/to/caller
    to: <existing callee>
    to_file: path/to/callee
    relation: calls
defects:
  - kind: <recommended label or unclassified>
    phase: plan-2
    details: <concrete failure evidence>
    remediation_hint: <bounded next action>
verifications:
  - cmd: "<command actually run>"
    result: pass | fail
    output_excerpt: "<short excerpt on failure>"
    observed:
      exit_code: 0
      tests_run: 12
```
<!-- mastermind:report-end -->

phases is the schema-v1 compatibility name for execution steps. New specs may use IDs such as plan-1; they do not need phase-shaped prose or checklists.

The machine source of truth is schemas/executor-report-v1.schema.json plus the stricter Rust consistency checks. Unknown fields, unsupported versions, duplicate step IDs, empty commands, contradictory complete reports, and reports over 1 MiB fail closed.

Field rules

• complete: every reported step is done, defects is empty, and every verification result is pass.
• partial or failed: at least one concrete defect is required.
• files_modified: the executor's evidence, not the scope authority. The controller calculates the real changed-file set from git and compares it with the spec.
• claims: only function_added and integration are understood by the deterministic audit. Use claims: [] for general prose outcomes.
• defects[].kind: a recommended routing label from defect-taxonomy.md, not a closed enum and not an instruction for automatic repair.
• verifications: record commands actually run. Do not claim an inferred or intended check.