[FEATURE] One breaking GitTarget API wave: the folder is described on the GitTarget #294

Tracking issue for one breaking wave on GitTarget. Design:
docs/layout/api-wave.md (lands with #318; it was
docs/design/gittarget-api-wave.md).

What changed since this was filed

The wave lost its centrepiece and gained a deletion. spec.layout was reversed — #319 made
kustomization registration an invariant, which retired three of the five arguments against path
templates, so the template stays and gains two additive fields instead
(docs/layout/model.md, #293). The placement work is no
longer breaking at all.

Three items have since been dropped or added:

• spec.mode: Observe|Write — dropped. Over a suspended target it bought only the difference
  between a pause and a declared posture. A suspended target that keeps scanning and publishing
  status.placement is the same adoption dry run with one field instead of two. suspend must
  keep observing, which deviates from Flux, where suspend stops reconciliation altogether; that
  goes in the field's docs.
• GitTarget.spec.interval — dropped. Every input that changes what a scan would conclude
  arrives as an event, on a watch. Flux polls because a Git remote cannot be watched, which is
  exactly why GitProvider.spec.interval stays. The residual gap (a folder someone else edits
  while we write nothing) is covered on demand by the reconcile-request annotation.
• The source-scope simplification — added. It deletes
  GitTarget.spec.allowedSourceNamespaces, so it breaks the same object B4 breaks and must ride
  the same bump. It is also the only member that makes the API smaller
  (docs/design/source-scope-simplification.md).

Why one wave rather than several changes

The consumer pins us three ways (image, Go module, require line), so each breaking release costs a
coordinated bump. That argues for batching, and it is the weaker half of the argument.

The stronger half survives in reduced form: several of these items are the same design decision seen
from different angles, and building them separately means deciding it several times, inconsistently.

The folder is described on the GitTarget. The connection describes only the connection.

• spec.suspend says whether we write to the folder.
• commitWindow and commit.message say how writes to it are batched and phrased, and today they
  live on GitProvider, which is the connection.
• serializeNamespace and kustomizeRoot say what the documents in it look like — and these are
  additive, so they ship without a bump.

Contents

• spec.layout — reversed; the additive serializeNamespace / kustomizeRoot work is not
  breaking and does not belong to this wave ([FEATURE] A layout is the declared thing, not a path: GitTarget.spec.layout #293)
• spec.mode: Observe|Write — dropped, see above
• spec.suspend + the requestedAt annotation and status.lastHandledReconcileAt
  (maintainer review F6). spec.interval on GitTarget — dropped; it stays on
  GitProvider, which polls
• commitWindow / commit.message move from GitProvider to GitTarget (config surface B4)
• The source-scope break: allowedSourceNamespaces removed, allowSourceNamespaceOverride →
  allowAnySourceNamespace, allowedNamespaces → accessFrom, sourceNamespace: "*"
  redefined as one cluster-wide list and watch
• CommitRequest TTL / ownerRef + the delete verb (maintainer review F10)
• CommitRequest.spec.author, SAR-guarded (consumer ci(deps): Bump softprops/action-gh-release from 1 to 2 #5)
• Movable destination via status.observedDestination (consumer deps(deps): Bump github.com/onsi/gomega from 1.36.1 to 1.38.0 #6)
• meta.LocalObjectReference for the name half of our reference shapes (F12)
• The TooManyStreams cap — sequenced after the * redefinition, which removes the
  fan-out it was written to bound
• The default ClusterProvider error message

Version stays v1alpha3: loud rejection of removed fields for one release, rather than paying for a
conversion path. The scope: Namespaced status-write envtest (F9) runs before any of this is
planned, because its answer constrains the enum work.