docs(api): CRD description proposal, its review, and its implementation

.devcontainer/devcontainer.json

@@ -83,7 +83,9 @@
         "golang.go",
         "ms-kubernetes-tools.vscode-kubernetes-tools",
         "ms-azuretools.vscode-docker",
-        "openai.chatgpt",
+        // Pinned: 26.1021.22027's webview never renders in the devcontainer
+        // (renderer_ready_timeout). Unpin once a newer release is confirmed working.
+        "openai.chatgpt@26.1007.21434",
         "anthropic.claude-code"
       ]
     }

.golangci.yml

@@ -390,6 +390,11 @@ linters:
       # caller that supplies a different path is its own test, into t.TempDir().
       - path: 'hack/crdfields/.*\.go'
         linters: [forbidigo, gosec]
+      # The API doc width check is a standalone dev CLI as well: its report is console
+      # output (forbidigo), and it reads the Go files it walks under the directories it is
+      # given, api/ by default (gosec G122/G304). It writes nothing.
+      - path: 'hack/apidocwidth/.*\.go'
+        linters: [forbidigo, gosec]
       # Allow fmt.Println in metrics exporter (initialization logs)
       - path: 'internal/telemetry/.*\.go'
         linters: [forbidigo]

AGENTS.md

@@ -118,7 +118,12 @@ See [Documentation checks](./CONTRIBUTING.md#documentation-checks).
   Field paths bare (`spec.prune.mode`), literal values in double quotes (`"Reapply"`), no
   backticks, no capitals for emphasis, no em dashes, no `docs/` paths and no implementation
   vocabulary the reader cannot see (branch worker, fact index). Aim for under 80 words; the few
-  fields that need more get short paragraphs. Conditions open with `Conditions are the latest
+  fields that need more get short paragraphs. Keep every line of doc comment text to 76
+  characters, measured after the `//` prefix and its space: `kubectl explain` keeps each line break and wraps every
+  line again, so a longer line leaves its last words on a line of their own
+  ([measurements](./docs/facts/crd-descriptions-in-kubectl-explain.md)). `task lint` checks
+  it (`lint-api-doc-width`). Use `-` bullets, continued with a two-space indent, when the
+  reader compares values or cases; keep prose where there is no choice. Conditions open with `Conditions are the latest
   observations of this <Kind>'s state.` and `spec`/`status` with `defines the desired/observed
   state of <Kind>.` An array item's Go type doc is also user-visible: it becomes `items`.
 - **Where that block goes matters, and getting it wrong fails silently.** On a FIELD, put it above

Taskfile-build.yml

@@ -246,6 +246,25 @@ tasks:
       - lint-actions
       - lint-helm
       - lint-docs
+      - lint-api-doc-width
+
+  lint-api-doc-width:
+    desc: Check that every API doc comment line fits in 76 characters, so kubectl explain prints it whole
+    # kubectl explain keeps a CRD description's line breaks and wraps each line again at
+    # 76 characters of text, so a wider line leaves its last words on a line of their own.
+    # See docs/facts/crd-descriptions-in-kubectl-explain.md.
+    #
+    # It reads api/ rather than config/crd/bases, so it needs no `manifests` dep: the CRDs
+    # also carry descriptions copied from upstream types (metav1.Condition, LabelSelector)
+    # that this repository cannot rewrap. hack/apidocwidth says more.
+    #
+    # Rooted globs only. CI asserts that a second `task lint` run finds this task up to
+    # date, and an unrooted `**` would walk external-sources/.
+    sources:
+      - api/**/*.go
+      - hack/apidocwidth/*.go
+    cmds:
+      - go run ./hack/apidocwidth
 
   lint-docs:
     desc: All documentation checks — references, markdown structure, prose, and metric names

api/v1alpha3/applierclaim_types.go

@@ -36,7 +36,8 @@ const (
 // KubeProvider admits the namespace it is in. A GitTarget that could name an
 // applier claim elsewhere would drive an applier that its own namespace was never admitted to.
 
-// ApplierClaimReference names an applier claim in the GitTarget's own namespace.
+// ApplierClaimReference names an applier claim in the GitTarget's own
+// namespace.
 type ApplierClaimReference struct {
 	// Kind is the applier claim's kind: "FluxClaim" or "ArgoCDClaim".
 	// +required
@@ -67,8 +68,8 @@ const (
 	ApplyReasonCatchUp ApplyReason = "CatchUp"
 )
 
-// SuspendState is whether an applier applied on its own. An Argo CD Application with automated sync
-// off counts as Suspended.
+// SuspendState is whether an applier applied on its own. An Argo CD
+// Application with automated sync off counts as Suspended.
 // +kubebuilder:validation:Enum=Suspended;NotSuspended
 type SuspendState string
 
@@ -108,42 +109,47 @@ func (p ApplyOperationPhase) Completed() bool {
 	return p == ApplyOperationSucceeded || p == ApplyOperationFailed
 }
 
-// ApplyOperation is an apply GitOps Reverser started on the applier claim's applier: the one in flight,
-// or the last one, once it completed. The branch worker writes it on every transition.
+// ApplyOperation is an apply GitOps Reverser started on the applier claim's
+// applier: the one in flight, or the last one, once it completed. The branch
+// worker writes it on every transition.
 type ApplyOperation struct {
-	// Phase is where the operation stands. Requested, Running, Settling (Flux only: applied, and
-	// the Kustomization not yet suspended again) and Unresolved (overdue, still followed) are in
-	// flight: the applier can still revert an edit to an object it applies, and is asked for
-	// nothing else. Succeeded and Failed are complete; Failed may have applied part of the commit.
+	// Phase is where the operation stands. Requested, Running, Settling (Flux
+	// only: applied, and the Kustomization not yet suspended again) and Unresolved
+	// (overdue, still followed) are in flight: the applier can still revert an
+	// edit to an object it applies, and is asked for nothing else. Succeeded and
+	// Failed are complete; Failed may have applied part of the commit.
 	// +required
 	Phase ApplyOperationPhase `json:"phase"`
 
-	// Reason is why the apply was asked for: ForeignCommit (a commit GitOps Reverser did not push),
-	// Refusal (a refused edit under spec.onRefusal: "Reapply"), Repair (an earlier apply reverted
-	// a newer API edit), or CatchUp (adopting objects the API created, and once at startup or when
-	// a GitTarget first names the claim). With several GitTargets on the claim, it is the strongest
-	// of their reasons.
+	// Reason is why the apply was asked for: ForeignCommit (a commit GitOps
+	// Reverser did not push), Refusal (a refused edit under spec.onRefusal:
+	// "Reapply"), Repair (an earlier apply reverted a newer API edit), or CatchUp
+	// (adopting objects the API created, and once at startup or when a GitTarget
+	// first names the claim). With several GitTargets on the claim, it is the
+	// strongest of their reasons.
 	// +optional
 	Reason ApplyReason `json:"reason,omitempty"`
 
-	// Commit is the commit the applier was asked to apply. Empty when the remote did not carry the
-	// branch.
+	// Commit is the commit the applier was asked to apply. Empty when the remote
+	// did not carry the branch.
 	// +optional
 	Commit string `json:"commit,omitempty"`
 
-	// Token identifies the request in the applier's own status: the reconcile.fluxcd.io/requestedAt
-	// value on a Flux object, or the "gitops-reverser request" entry in an Argo CD operation's info.
+	// Token identifies the request in the applier's own status: the
+	// reconcile.fluxcd.io/requestedAt value on a Flux object, or the
+	// "gitops-reverser request" entry in an Argo CD operation's info.
 	// +optional
 	Token string `json:"token,omitempty"`
 
-	// SuspendToken is the reconcile.fluxcd.io/requestedAt value of the suspend that follows the
-	// apply. Once the Kustomization reports it handled, nothing started before the suspend is still
-	// running. Flux only.
+	// SuspendToken is the reconcile.fluxcd.io/requestedAt value of the suspend
+	// that follows the apply. Once the Kustomization reports it handled, nothing
+	// started before the suspend is still running. Flux only.
 	// +optional
 	SuspendToken string `json:"suspendToken,omitempty"`
 
-	// AppliedRevision is the revision the applier reports applying when the operation completes.
-	// It can differ from commit when the branch moved between the check and the apply.
+	// AppliedRevision is the revision the applier reports applying when the
+	// operation completes. It can differ from commit when the branch moved between
+	// the check and the apply.
 	// +optional
 	AppliedRevision string `json:"appliedRevision,omitempty"`
 
@@ -155,13 +161,15 @@ type ApplyOperation struct {
 	// +optional
 	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`
 
-	// Message says why a Failed operation failed, or why an Unresolved one is overdue.
+	// Message says why a Failed operation failed, or why an Unresolved one is
+	// overdue.
 	// +optional
 	Message string `json:"message,omitempty"`
 }
 
-// ApplierClaim is what every applier claim kind answers, so the controllers, the branch workers and the
-// dispatcher handle a FluxClaim and an ArgoCDClaim alike.
+// ApplierClaim is what every applier claim kind answers, so the controllers,
+// the branch workers and the dispatcher handle a FluxClaim and an ArgoCDClaim
+// alike.
 // +kubebuilder:object:generate=false
 type ApplierClaim interface {
 	metav1.Object