agents|feat: Plan provenance and trust-tiered orchestration

[williamthorsen]

Description

The orchestration pipeline treats all external plans uniformly: when externalPlan: true, both architecture and planning phases are forced to run regardless of the plan's origin, freshness, or quality. This produces 3-4 minutes of redundant validation when a plan was just created by a trusted skill like design-and-plan or refine-plan.

Evidence from ticket #247 (run 20260310-071948Z):

• Architecture phase: 80 seconds, produced "low impact" with no corrections
• Planning phase: 123 seconds, adopted the plan with zero meaningful deviations
• Savings analysis finding C1 confirms the architecture phase "did not materially de-risk the implementation"

The solution adds provenance headers to plan artifacts (YAML frontmatter with skill, timestamp, baseSha, etc.) and trust-tiered phase skipping to the orchestration pipeline. Plans from known skills against an unchanged codebase skip architecture and planning entirely; plans with some divergence get lighter validation; unknown plans get full validation (current behavior).

Acceptance criteria

Must have

• design-and-plan emits provenance headers in plan artifacts (skill, timestamp, baseSha, isInteractive)
• refine-plan reads, updates, and writes provenance headers (preserves skill, increments iteration, updates baseSha)
• Orchestrator parses provenance headers and computes trust tiers (high/medium/low)
• High-trust plans (credible source + baseSha matches main) skip architecture and planning phases
• High-trust plans get orchestrator-generated orchestration-plan.json (with JSON companion detection)
• Medium-trust plans (credible source + baseSha diverged) skip architecture, run planning in adoption mode
• Low-trust plans and plans without provenance get current behavior (full validation)
• Trust tier is recorded in run-index.json config as planTrust
• Phase decision events include trust-based skip reasons

Should have

• plan-orchestrable-steps emits provenance headers
• Phase 3 coder prompt uses {plan-md-path} is set conditional (not planning phase ran) to handle high-trust skip
• Run summary includes plan trust row with skill name and freshness classification

Nice to have

• writing-plans (external superpowers plugin) emits provenance headers (requires coordinated plugin update)

[williamthorsen]

Implementation notes (from planning session, 2026-03-10)

These notes capture initial exploration and a proposed approach.
The implementer should verify assumptions and adapt as needed.

Design spec

See docs/superpowers/specs/2026-03-10-plan-provenance-and-trust-design.md (removed from source control; available as local artifact).

Key concepts

Provenance header

Plan-producing skills embed YAML frontmatter in plan artifacts:

---
provenance:
  skill: design-and-plan          # required
  timestamp: 2026-03-10T07:18:11Z # required
  baseSha: abc123...              # optional: SHA of main at creation
  isInteractive: true             # optional: defaults to false
  iteration: 2                    # optional: defaults to 1
---

Trust tiers

• High (credible source + baseSha matches main): Skip architecture + planning
• Medium (credible source + baseSha diverged): Skip architecture, run planning in adoption mode
• Low (unknown source or stale): Full validation (current behavior)

Affected skills

1. design-and-plan — emit provenance header
2. refine-plan — read/update/write provenance header
3. plan-orchestrable-steps — emit provenance header
4. orchestrate — parse provenance, compute trust, adjust pipeline

Implementation plan

9 tasks across 3 chunks:

• Chunk 1 (Tasks 1-3): Provenance header emission in plan-producing skills
• Chunk 2 (Tasks 4-7): Orchestrator trust scoring and pipeline changes
• Chunk 3 (Tasks 8-9): Run summary updates and verification

---

Plan artifact: ~/repos/vaults/code-artifacts/projects/codeassembly/tickets/263/20260310-1545Z_plan-provenance_plan.md

[williamthorsen]

Insight: writing-plans needs provenance headers

The writing-plans skill (external superpowers plugin) is a plan-producing skill that should emit provenance headers, but it was intentionally excluded from #263 because it requires a coordinated plugin update. When updating the superpowers plugin, add provenance header emission following the same pattern as design-and-plan:

---
provenance:
  skill: writing-plans
  timestamp: <timestamp>
  baseSha: <baseSha>
---

The orchestrator already includes writing-plans in the credible skills list for trust scoring — it just needs the headers emitted.