feat: validate collaboration and sub-agent evidence

[smota]

Epic: #115

Background & Problem Statement

AgentFlow already records role-pass, execution-target, capability, and attribution evidence. As harness leverage increases, evidence needs to stay compact while becoming more precise. Sub-agent use, bounded loops, collaboration plans, councils, and isolated worktrees need validation so agents cannot make weak or false claims.

Proposed Solution

Extend AgentFlow evidence contracts and validators for intelligent collaboration. Keep raw helper discussion local/summarized, but validate the durable evidence needed for trust.

Requirements

• Define delegated-subagent evidence schema.
• Define collaboration-plan evidence schema.
• Define bounded-loop evidence schema.
• Define bounded-environment evidence schema.
• Define strategy synthesis, dissent log, and critique disposition shape.
• Add PR manifest/workflow-status fields for collaboration mode and helper evidence.
• Validate no false council, sub-agent, or multi-agent claims.
• Keep raw transcripts out of durable evidence by default.

Technical Design

Evidence should support compact summaries:

{
  "collaborationMode": "council",
  "reason": "architecture uncertainty",
  "helpers": [
    {
      "role": "risk-scout",
      "executor": "pi-subagent",
      "permissions": "read-only",
      "artifact": ".agent-runs/issues/123/council/risk-scout.md"
    }
  ],
  "synthesis": ".agent-runs/issues/123/strategy-synthesis.md",
  "dissent": "testability scout preferred Option C; deferred to follow-up #N"
}

Validators should reject:

• missing transport/delegation/context boundary for active sub-agent use;
• unbounded loops;
• write access from multiple shared-worktree helpers;
• council claims without helper rows;
• multi-agent review claims without independent role intelligence;
• PR readiness without collaboration summary when helpers were used.

Feature Tracking

• Add delegated-subagent evidence schema.
• Add bounded-loop evidence schema.
• Add collaboration-plan evidence schema.
• Add bounded-environment evidence schema.
• Add strategy synthesis and dissent artifacts.
• Update PR manifest and workflow-status templates.
• Add validators and tests.
• Add examples of accepted/rejected evidence.

Acceptance criteria

• Agent evidence stays concise but checkable.
• Validators catch false collaboration and unsafe helper claims.
• Existing single-agent evidence remains valid with minimal/no extra fields.
• PR reviewers can see what helper intelligence was used and why.

Test plan

• Unit tests for validators.
• pnpm test.
• pnpm test:workflow.
• pnpm format:check.
• Fixture tests for valid/invalid collaboration evidence.

Workflow classification

• Profile: standard
• Risk: medium
• Effort: high
• Change surfaces: tooling, templates, docs
• Review: independent review recommended.

Agent-builder/schema refinement

Evidence validation should satisfy agent-builder's tool/action contract expectations while staying portable and non-platform-hosted.

Additional requirements

• Define JSON Schema for collaboration evidence, delegated-subagent evidence, bounded-loop evidence, bounded-environment evidence, strategy synthesis, and critique disposition.
• State explicitly that MCP/OpenAPI runtime tooling is optional and not required for the first implementation.
• If MCP/OpenAPI adapters are later introduced, ensure they preserve the same confirmation, rollback, audit, fallback, and permission boundaries.
• Validate context-efficiency fields where helpers are used: durable summary path, raw transcript local-only status, and parent synthesis path.

Acceptance criteria additions

• Schemas are reusable by validators, PR manifests, role-passes, and future harness adapters.
• Single-agent evidence remains valid without collaboration fields unless helpers/patterns were actually used.

[github-actions]

Integrated into development by PR #116: #116

Merge commit: 5d08ddbe7e3cefe8fe59d9421a86cea781514495
Release/promotion to main is tracked separately.

[github-actions]

Integrated into development by PR #117: #117

Merge commit: 0a19c0a24cb234e21f9f48dd7034f0a4a7ad55bd
Release/promotion to main is tracked separately.