Merge pull request #142 from LAA-Software-Engineering/feat/112-config-resolution

feat(config,spec): user-local config, resolved snapshot, strict YAML (#112)

Author: leo-aa88

.gitignore

@@ -36,3 +36,5 @@ go.work.sum
 
 tmp/
 examples/**/.agentic/
+**/.agentic/local.yaml
+**/.agentic/resolved-config.json

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Config resolution hardening** (issue #112): user-local overlays (`~/.config/agentctl/config.yaml`, `.agentic/local.yaml`), strict unknown-key rejection in all YAML layers, and an immutable resolved-config snapshot (`.agentic/resolved-config.json`) with digest checks across `validate`/`plan`/`apply` → `run` (exit **3** on drift). `plan` JSON/YAML includes `resolvedConfigDigest`.
 - **Run attribution** (issue #111): `tenant_id`, `thread_id`, `actor_id`, `parent_run_id`, `request_id`, `idempotency_key`, and `source` on `runs`; trace events carry matching tenant/thread/actor for filterable logs and inspector queries. `agentctl run` accepts `--tenant-id`, `--thread-id`, `--actor-id` (local defaults `tenant-1` / `thread-1` / `user-1`); `agentctl logs` and `GET /api/runs` filter by the same dimensions. `--resume` reuses persisted `run_id` and `thread_id`. OTel spans emit `gen_ai.tenant.id`, `gen_ai.thread.id`, `gen_ai.actor.id`, and `gen_ai.request.id`. See [`docs/ATTRIBUTION.md`](docs/ATTRIBUTION.md).
 - **Trace payload redaction** (issue #110): trace events are sanitized, key-redacted, and size-capped before SQLite storage. Defaults mask common secret key names; override via `Project.spec.traces.redactKeys`, `maxPayloadBytes`, and `spec.traces.redaction` (`maxDepth`, `maxBytes` for binary previews, `maxStringChars`). HITL edit `argsDiff` is redacted before persistence. Local runs use [trace.NewRecorderForGraph] from project spec.
 - **Optional OpenTelemetry trace export** (issue #108): `Project.spec.telemetry` (`enabled`, `serviceName`, `endpoint` with `env:` tokens, `consoleExport`) emits WayFind-aligned `gen_ai.*` spans (`agent.run`, `model.chat`, `tool.exec`, `approval`) alongside SQLite traces. Disabled by default; init failures log a warning and never fail runs. See [`docs/OTEL.md`](docs/OTEL.md) for a Jaeger quick start.

README.md

@@ -164,7 +164,20 @@ Notes:
 | `-o` / `--output` | `table`, `json`, or `yaml` |
 | `--no-color` | ASCII-friendly validate output |
 
-Exit codes are summarized in **section 11.2** of [`docs/DESIGN_DOC.md`](docs/DESIGN_DOC.md) (`0` success, `2` validation, **`3` plan/apply conflict** when deployment state changed after `plan`, `4` execution, `5` policy denial, …).
+Exit codes are summarized in **section 11.2** of [`docs/DESIGN_DOC.md`](docs/DESIGN_DOC.md) (`0` success, `2` validation, **`3` plan/apply conflict** when deployment state changed after `plan` or resolved config drifted before `run`, `4` execution, `5` policy denial, …).
+
+### User-local config (per-developer overrides)
+
+Config is resolved in this order (highest wins): **CLI flags** → **environment overlay** (`-e`) → **project YAML** → **user-local** → **built-in defaults**.
+
+Optional user-local files (git-ignored, strict YAML — typos fail `validate`):
+
+| Path | Scope |
+|------|--------|
+| `$XDG_CONFIG_HOME/agentctl/config.yaml` or `~/.config/agentctl/config.yaml` | Global per-user defaults (`defaults`, `state`, `providers`, `traces`, `telemetry`) |
+| `.agentic/local.yaml` under `--project` | Project-scoped overrides (same fields; wins over the global file) |
+
+`validate`, `plan`, and `apply` write `.agentic/resolved-config.json` (digest of the resolved graph + env + state path). `run` rejects drift from that snapshot with exit **3** — re-run `validate` or `plan` after changing config.
 
 ---
 
@@ -175,6 +188,7 @@ Exit codes are summarized in **section 11.2** of [`docs/DESIGN_DOC.md`](docs/DES
 | `cmd/agentctl` | CLI entrypoint |
 | `internal/cli` | Cobra commands, flags, golden tests |
 | `internal/spec` | YAML types, normalize, validate |
+| `internal/config` | Layered config resolution, immutable snapshot |
 | `internal/project` | Load project + imports |
 | `internal/plan` | Planner and risk summary |
 | `internal/apply` | Apply plan to deployment store |

internal/cli/apply.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/apply"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/config"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/plan"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/render"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
@@ -70,16 +71,13 @@ func runApply(cmd *cobra.Command, flagAutoApprove bool) error {
 	g := Globals()
 	approved := flagAutoApprove || envAutoApproveEnabled()
 
-	graph, root, err := prepareProjectGraph(g.ProjectRoot, g)
+	rc, err := prepareResolvedConfig(g)
 	if err != nil {
 		return NewExitError(ExitValidationError, err)
 	}
-
-	env := planEnvironment(g)
-	dsn, err := resolveStateSQLitePath(root, graph, g.StatePath)
-	if err != nil {
-		return fmt.Errorf("apply: resolve state path: %w", err)
-	}
+	graph := rc.Graph()
+	env := rc.Environment()
+	dsn := rc.StatePath()
 	if err := os.MkdirAll(filepath.Dir(dsn), 0o755); err != nil {
 		return fmt.Errorf("apply: create state directory: %w", err)
 	}
@@ -96,7 +94,10 @@ func runApply(cmd *cobra.Command, flagAutoApprove bool) error {
 	}
 
 	if len(pl.Operations) == 0 {
-		return writeApplyEmptyOutput(cmd, env, dsn, pl, g)
+		if err := writeApplyEmptyOutput(cmd, env, dsn, pl, rc, g); err != nil {
+			return err
+		}
+		return config.WriteSnapshot(rc)
 	}
 
 	if g.Output != render.FormatTable {
@@ -133,7 +134,10 @@ func runApply(cmd *cobra.Command, flagAutoApprove bool) error {
 		return fmt.Errorf("apply: %w", err)
 	}
 
-	return writeApplySuccessOutput(cmd, env, dsn, pl, g, at)
+	if err := writeApplySuccessOutput(cmd, env, dsn, pl, rc, g, at); err != nil {
+		return err
+	}
+	return config.WriteSnapshot(rc)
 }
 
 func readApplyConfirmation(r io.Reader) (bool, error) {
@@ -145,16 +149,16 @@ func readApplyConfirmation(r io.Reader) (bool, error) {
 	return s == "y" || s == "yes", nil
 }
 
-func writeApplyEmptyOutput(cmd *cobra.Command, env, dsn string, pl *plan.Plan, g *Global) error {
+func writeApplyEmptyOutput(cmd *cobra.Command, env, dsn string, pl *plan.Plan, rc *config.ResolvedConfig, g *Global) error {
 	out := cmd.OutOrStdout()
 	switch g.Output {
 	case render.FormatJSON:
-		m := planJSONModel(env, dsn, pl)
+		m := planJSONModel(env, dsn, pl, rc)
 		m["applied"] = false
 		m["message"] = "no changes"
 		return render.WriteJSON(out, m)
 	case render.FormatYAML:
-		m := planJSONModel(env, dsn, pl)
+		m := planJSONModel(env, dsn, pl, rc)
 		m["applied"] = false
 		m["message"] = "no changes"
 		return render.WriteYAML(out, m)
@@ -164,17 +168,17 @@ func writeApplyEmptyOutput(cmd *cobra.Command, env, dsn string, pl *plan.Plan, g
 	}
 }
 
-func writeApplySuccessOutput(cmd *cobra.Command, env, dsn string, pl *plan.Plan, g *Global, at time.Time) error {
+func writeApplySuccessOutput(cmd *cobra.Command, env, dsn string, pl *plan.Plan, rc *config.ResolvedConfig, g *Global, at time.Time) error {
 	out := cmd.OutOrStdout()
 	c, u, d := planCounts(pl)
 	switch g.Output {
 	case render.FormatJSON:
-		m := planJSONModel(env, dsn, pl)
+		m := planJSONModel(env, dsn, pl, rc)
 		m["applied"] = true
 		m["appliedAt"] = at.Format(time.RFC3339Nano)
 		return render.WriteJSON(out, m)
 	case render.FormatYAML:
-		m := planJSONModel(env, dsn, pl)
+		m := planJSONModel(env, dsn, pl, rc)
 		m["applied"] = true
 		m["appliedAt"] = at.Format(time.RFC3339Nano)
 		return render.WriteYAML(out, m)

internal/cli/diff.go

@@ -101,7 +101,7 @@ func runDiff(cmd *cobra.Command, args []string) error {
 	ctx := context.Background()
 	g := Globals()
 
-	graph, root, err := prepareProjectGraph(g.ProjectRoot, g)
+	graph, root, err := prepareProjectGraph(g)
 	if err != nil {
 		return NewExitError(ExitValidationError, err)
 	}

internal/cli/diff_test.go

@@ -49,7 +49,7 @@ func TestDiff_afterApply_noDifferences(t *testing.T) {
 	db := filepath.Join(t.TempDir(), "diff2.db")
 
 	g := &Global{ProjectRoot: root}
-	graph, _, err := prepareProjectGraph(root, g)
+	graph, _, err := prepareProjectGraph(g)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -87,7 +87,7 @@ func TestDiff_singleResource_inSync(t *testing.T) {
 	db := filepath.Join(t.TempDir(), "diff3.db")
 
 	g := &Global{ProjectRoot: root}
-	graph, _, err := prepareProjectGraph(root, g)
+	graph, _, err := prepareProjectGraph(g)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -126,7 +126,7 @@ func TestDiff_singleResource_policyUpdate(t *testing.T) {
 	db := filepath.Join(t.TempDir(), "diff4.db")
 
 	g := &Global{ProjectRoot: root}
-	graph, _, err := prepareProjectGraph(root, g)
+	graph, _, err := prepareProjectGraph(g)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -269,7 +269,7 @@ func TestDiff_json_inSyncSingleTarget(t *testing.T) {
 	db := filepath.Join(t.TempDir(), "diff9.db")
 
 	g := &Global{ProjectRoot: root}
-	graph, _, err := prepareProjectGraph(root, g)
+	graph, _, err := prepareProjectGraph(g)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/cli/golden_test.go

@@ -108,7 +108,7 @@ func TestGolden_plan_noop_after_apply_table(t *testing.T) {
 	db := filepath.Join(t.TempDir(), "golden-plan2.db")
 
 	g := &Global{ProjectRoot: root}
-	graph, _, err := prepareProjectGraph(root, g)
+	graph, _, err := prepareProjectGraph(g)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/cli/init_test.go

@@ -52,7 +52,7 @@ func TestInit_defaultPolicyExpandsShellSafePreset(t *testing.T) {
 
 	ResetGlobalsForTest()
 	g := &Global{ProjectRoot: filepath.Join(parent, name)}
-	graph, _, err := prepareProjectGraph(g.ProjectRoot, g)
+	graph, _, err := prepareProjectGraph(g)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/cli/inspect.go

@@ -119,7 +119,7 @@ func runInspect(cmd *cobra.Command, args []string) error {
 		return NewExitError(ExitValidationError, fmt.Errorf("inspect: %w", err))
 	}
 	gl := Globals()
-	graph, _, err := prepareProjectGraph(gl.ProjectRoot, gl)
+	graph, _, err := prepareProjectGraph(gl)
 	if err != nil {
 		return NewExitError(ExitValidationError, err)
 	}

internal/cli/inspect_web.go

@@ -19,7 +19,7 @@ func runInspectWeb(cmd *cobra.Command, port int, traceUIBase string) error {
 		return NewExitError(ExitValidationError, err)
 	}
 	g := Globals()
-	graph, root, err := prepareProjectGraph(g.ProjectRoot, g)
+	graph, root, err := prepareProjectGraph(g)
 	if err != nil {
 		return NewExitError(ExitValidationError, err)
 	}