PRD: Add Execution Environment Validator to cc-devflow task contracts

[Dimon94]

Problem Statement

cc-devflow already asks agents to freeze task.md scope before execution, but the execution-environment rules are mostly enforced by prose. That leaves a dangerous gap: a plan can look ready while missing required environment sections, child dispatch boundaries, task assignments, dependency readiness, or obvious sibling-worktree conflicts. The user needs a small, deterministic gate that turns these contract failures into machine-readable evidence before cc-plan freezes work and before cc-dev dispatches children.

Solution

Add an Execution Environment Validator owned by the Execution Environment Contract chain skill. The validator reads a frozen task document plus optional live environment/running-sibling evidence, emits a stable JSON fact report, and fails closed only for true contract errors. It does not become a full task parser, workflow compiler, scheduler, or dispatch packet generator. It exists to make the already-agreed cc-devflow environment contract auditable and executable.

The recommended testing seam is one high-level validator seam: invoke the validator with task text and optional evidence inputs, then assert the external JSON report, issue levels, stable codes, and exit behavior. Tests should not bind to internal parsing helpers.

User Stories

1. As a cc-plan user, I want missing execution-environment sections detected before freeze, so that an invalid plan cannot become durable work.
2. As a cc-dev user, I want dispatch boundaries checked before child work starts, so that children only receive work they are allowed to execute.
3. As a parent agent, I want assigned task IDs validated against the dispatch boundary, so that a child cannot silently receive an unassigned or out-of-scope task.
4. As a reviewer, I want dependency readiness reported separately from syntax validity, so that blocked dispatch is visible without pretending the task document is malformed.
5. As a workflow maintainer, I want stable machine-readable issue codes, so that tests and future tooling can depend on facts instead of prose.
6. As an operator, I want error, blocker, and warning levels, so that plan-freeze failures, dispatch blockers, and advisory findings have distinct operational meaning.
7. As a cc-check or cc-review executor, I want completed to count as dependency-ready, so that verification-only stages can unlock downstream work without requiring integration.
8. As a cc-do or cc-diagnose executor, I want completed to remain insufficient for dependency readiness, so that implementation work cannot bypass integration evidence.
9. As a parallel execution planner, I want obvious touch/resource conflicts with running sibling work reported, so that the parent can avoid self-inflicted collisions.
10. As a chain-skill maintainer, I want conflict detection to stay simple through normalized prefix matching, so that MVP behavior is predictable and not a hidden glob/pathspec engine.
11. As a task author, I want serial and parallel templates to use the same checker when execution environments are present, so that the contract has one enforcement path.
12. As a future maintainer, I want the validator to report dispatch block existence and line numbers without generating packets, so that validation stays separate from orchestration.
13. As a documentation reader, I want the glossary and ADR to name the validator and its non-goals, so that ownership does not drift into cc-dev or a generic compiler layer.
14. As an agent using cc-plan, I want the skill text to mention the validator at freeze time, so that invalid tasks are caught before they become a false source of truth.
15. As an agent using cc-dev, I want the skill text to mention the validator before dispatch, so that child work starts only after the environment contract has evidence.
16. As the repo owner, I want the smallest useful validator rather than a broad architecture rewrite, so that the improvement reduces ambiguity without turning cc-devflow into a new platform.

Implementation Decisions

• The validator is owned by the Execution Environment Contract chain skill because the contract is shared by planning and development stages.
• cc-plan and cc-dev should reference the validator at their respective freeze/dispatch gates.
• cc-do should not own or duplicate this logic; it receives already-scoped work.
• The validator requires a task input and may accept optional environment and running-sibling evidence.
• The CLI emits JSON on stdout.
• Usage errors and missing input files exit with a distinct usage/file-missing status.
• Contract error issues exit non-zero and block freeze/dispatch.
• Dispatch blocker issues are reported as blockers without being collapsed into malformed-task errors.
• Advisory warning issues are report-only.
• MVP issue codes are missing-section, invalid-env-row, missing-dispatch-boundary, missing-assigned-task, task-outside-boundary, dependency-not-ready, running-touch-conflict, and running-resource-conflict.
• Dependency readiness treats integrated, skipped, and verification-stage completed as ready.
• Implementation-stage completed does not satisfy downstream dependency readiness.
• Running sibling conflict detection uses normalized string prefix matching only.
• The validator reports dispatch block presence and line information; it does not generate child task packets.
• The change should add a short ADR recording owner, scope, and non-goals.
• The domain glossary should name Execution Environment Validator as the machine-checkable gate for execution-environment contract evidence.

Testing Decisions

• Test the validator through its highest external seam: task/evidence input to JSON report and process result.
• Tests should verify externally observable behavior: issue levels, stable codes, readiness result, and exit semantics.
• Tests should not depend on internal helper names or parser structure.
• Prior art is the existing execution-environment contract test coverage around task template expectations.
• Required cases include missing execution-environment section, missing dispatch boundary, assigned task missing inside boundary, implementation dependency marked only completed, verification dependency marked completed, and running touch-prefix conflict.
• A focused test command for the execution-environment contract area must pass before implementation is considered complete.

Out of Scope

• Full task.md parser or DSL.
• Workflow compiler.
• Child packet generation.
• Dispatch scheduling strategy.
• Git state validation.
• Pathspec or glob conflict engine.
• TDD prose-quality enforcement.
• Rewriting cc-devflow stage semantics.
• Moving execution-environment ownership into cc-dev or generic libraries.

Further Notes

The architectural center is fail-closed contract evidence, not automation breadth. The validator should remove ambiguity at the parent/child boundary while keeping orchestration, implementation, and review concerns separate.