Merge pull request #91 from LAA-Software-Engineering/docs/clarify-normalize-vs-env-79

docs(spec): clarify NormalizeProjectGraph vs ApplyEnvironment (#79)

Author: leo-aa88

internal/runtime/local/runtime.go

@@ -29,7 +29,9 @@ func (r *Runtime) now() time.Time {
 	return time.Now().UTC()
 }
 
-// ApplyEnvironment returns a shallow copy of g with Environment overrides applied (design doc section 7.6 MVP).
+// ApplyEnvironment returns a shallow copy of g with Environment overrides applied (design doc §7.6 MVP).
+// Call after spec.NormalizeProjectGraph so Project.spec.defaults are merged first; agentctl and
+// [Runtime.ExecuteWorkflow] use that order before spec.ValidateProjectGraph.
 func ApplyEnvironment(g *spec.ProjectGraph, envName string) (*spec.ProjectGraph, error) {
 	envName = strings.TrimSpace(envName)
 	if envName == "" || g == nil {

internal/spec/doc.go

@@ -1,4 +1,6 @@
 // Package spec defines resource envelopes, MVP kind structs (§6–§7), YAML loading,
 // project-level defaults ([NormalizeProjectGraph]), reference resolution ([ResolveReferences]),
 // and graph validation ([ValidateProjectGraph], §9.1–§9.5 MVP subset).
+// Environment-specific overrides (§7.6) are applied by [github.com/LAA-Software-Engineering/agentic-control-plane/internal/runtime/local.ApplyEnvironment]
+// after [NormalizeProjectGraph] in CLI and local-runtime flows.
 package spec

internal/spec/normalize.go

@@ -12,7 +12,10 @@ import "strings"
 //   - Workflow.spec.policy  ← defaults.policy when the workflow omits policy.
 //   - Workflow.spec.runtime ← defaults.runtime when the workflow omits runtime (issue #76).
 //
-// Environment overrides are out of scope (issue #4). Mutates graphs in place.
+// Environment overlays (design doc §7.6) are not applied here. Typical pipelines load the graph,
+// run NormalizeProjectGraph, then apply the selected environment with ApplyEnvironment in
+// internal/runtime/local (e.g. agentctl validate/plan/apply/run, local ExecuteWorkflow), and
+// finally validate. Mutates g in place.
 func NormalizeProjectGraph(g *ProjectGraph) {
 	if g == nil {
 		return