Process-config template-specificity enforcement (V-21)

[PolyphonyRequiem]

Overview

Closes the footgun where a process-config.yaml with scope_removed: Removed passes all current validation but fails at runtime when twig state Removed is called against an ADO Basic project (which has no Removed state — only To Do, Doing, Done).

Supports Epic #521 (mission north star) by giving consumers safe, per-template defaults when onboarding. A self-contained polyphony package that ships with a one-size-fits-all config that breaks on ADO Basic is not consumable without manual correction.

---

Scope

1. Extend ConfigValidator to validate state names against the process template's state set

   • Accept process_template + states: table as part of the validation context
   • For every state name in transitions: (right-hand side), assert it exists in the template's known state set
   • Source of truth for state sets: twig2/tests/Twig.TestKit/ProcessConfigBuilder.cs:48-96
   • Closes V-21 validation rule (referenced in docs/polyphony-architecture.md:36 but not enforced in code)

2. Ship per-template config scaffolds

   • .polyphony-config/scaffold/ — add process-config.basic.yaml (ADO Basic: To Do / Doing / Done), process-config.agile.yaml (ADO Agile: Active / Resolved / Closed / Removed etc.), process-config.scrum.yaml
   • Each scaffold is valid for its template; onboarding operators copy the correct one rather than editing the default

3. Document the template-specificity rule prominently

   • docs/polyphony-process-config-schema.md — add a banner warning that state names on the right side of transitions: are template-specific; link to the scaffold directory

---

Source of record

• Bach concern feat: Phase Detection, Routing Engine, and Command Implementations (PG-3) AB#2593 AB#2594 #2 (2026-05-28 fan-out): scope_removed: Removed invalid in ADO Basic
• docs/polyphony-architecture.md:233-263 (§The footgun) + lines 36 (V-21 rule)
• docs/polyphony-process-config-schema.md:244-263
• .polyphony-config/process-config.yaml:25, 30, 34 — hardcodes Removed everywhere

---

Acceptance criteria

• ConfigValidator rejects a process-config.yaml with state names invalid for the declared process template
• V-21 validation rule is enforced (not just documented)
• Per-template config scaffolds exist for ADO Basic, Agile, and Scrum
• docs/polyphony-process-config-schema.md updated with template-specificity banner
• Existing tests pass; new unit test for V-21 violation added

---

In-situ clause

Apply DU patterns and hygiene fixes opportunistically where natural in your scope. Don't make these the primary focus.

---

Created by Beethoven (Mission Keeper) — 2026-05-28