refresh: audit hooks/mcp/settings projection reads against config layers

[NikashPrakash]

Ground-truth audit of a field report claiming da refresh dropped hook
projections because the projection path consulted the flat repo-local
hooks boolean instead of the layer-resolved effective value — the same
"layered-consumer-left-behind" class as the earlier relevance /
loadFlatSnapshot gap, and framed as completing #535 (which fixed only
the marshal side).

The report does not hold, and the reason is not the one either side expected.

What the audit found

hooks, mcp, and settings are read at projection time neither flat
nor effective — they are not read at all. The three keys participate in
the layer merge (so da config explain hooks correctly reports an org
layer's true), but no projection path consumes the resolved value. Hook,
MCP, and settings projection is driven entirely by what exists under
~/.agents/{hooks,mcp,settings}/<scope>/, via internal/platform's
resolveHookSpec / resolveScopedFile. Neither internal/platform nor
internal/links loads a manifest at all.

Every non-test read of the three fields:

file:line	read	decides
commands/internal/lifecycle/install.go:586-588	flat rc.Hooks/MCP/Settings	display only — the install --generate --dry-run preview
internal/config/agentsrc.go:1496-1498	pickStringsOrBool / pickBool	whether a fresh scan overwrites an author-committed declaration
internal/config/agentsrc.go:1112-1114, :1185-1187	field copy	serialization round-trip

There is no Snapshot.Effective.Hooks/MCP/Settings read anywhere, no
ExtraFields["hooks"]-style read (all three are in agentsRCKnown, so
they can never land there), and no StringsOrBool.Contains call outside
tests. The last behavioral consumer was a da status display line removed
in 70f23a3. There is no shell implementation left to hide one.

Verified end to end in a sandboxed HOME/AGENTS_HOME, reproducing the
reported shape: manifest omits hooks, a local extends layer supplies
hooks: true.

$ da config explain hooks
Field:   hooks
Value:   true
Layer stack:
  [1] product-defaults       -> not set
  [2] org:org/base.json      -> true   <- active
  [3] repo-local             -> not set

$ da refresh e2eproj      # → .claude/settings.local.json carries the hook

Same result with hooks:false, hooks:true, or the key absent, with or
without a layer: the projected artifacts are byte-identical. The flag gates
nothing.

What this PR does

No behavior change. Two commits:

1. TestRunRefresh_ProjectionIgnoresHooksMCPSettingsFlags — drives the real
   runRefresh over five manifest/layer combinations and asserts both halves
   together: the merge precedence (via ResolveLocked, the surface config explain uses) and the projected artifacts (rendered hook command in
   .claude/settings.local.json, .mcp.json, .cursor/settings.json).
   The absent-key + org-layer-true row is the reported shape and is what
   would fail if anyone later wired projection to a flat read.

2. Corrects the AgentsRC field comment and the three schema descriptions,
   which asserted that an explicit repo-local false "disables the org
   layer's projection." It does not — it wins the merge and changes what
   config explain reports.

Why not just wire the flags in

Honoring the flags would be a behavior change, not a fix. Manifests written
before the pointer migration carry an injected "hooks": false their authors
never wrote (that injection is exactly what #535 stopped). Gating projection
on the resolved value would disable hook projection for every such repo the
next time it refreshes. That needs a deliberate decision plus a migration
story; this PR pins the current contract so the change shows up as a
reviewed diff rather than a silent one.

Same-class flat reads found nearby (reported, not changed)

• gitignore_projections — commands/internal/lifecycle/gitignore.go:52,61.
  The one real flat-read behavioral gate at projection time, reached from
  both refresh and install. Deliberate and documented as such; left alone.
• sources at install — commands/internal/lifecycle/install.go:184 resolves
  flat rc.Sources while skills/agents link from Snapshot.Effective
  (:196). Mitigated by design: linkInstallResources always appends
  config.AgentsHome(), so a layer-supplied skill still resolves from the
  home store. Worth a look, not obviously broken.
• kg.graph_home (commands/workflow/graph.go:87) and observability.*
  (commands/observability/cmd.go:64,317-326,
  commands/workflow/observability_hook.go:94,171) are flat reads of
  layer-mergeable keys, so an org layer setting them is invisible. Outside
  the projection/lifecycle layer and adjacent to in-flight commands/kg
  work, so untouched here.
• features has no consumer at all outside config explain --flags.

Verification

• go test ./internal/... -skip TestConfigLoadSave — pass
• go test ./commands/... — pass
• go test ./... -skip TestConfigLoadSave — pass
• gofmt, go vet ./commands/... ./internal/config/... — clean
• Sandboxed HOME/AGENTS_HOME E2E as above; no real repo or home touched

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
99.2% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud