feat: add doc comment structure compliance test

TestDocCommentStructure verifies exported functions with
parameters have Parameters: sections and functions with
return values have Returns: sections, per CONVENTIONS.md.
68 pre-existing violations grandfathered; new code must
not increase the count.

Supersedes the ctx-docstrings skill task — deterministic
test enforcement is stronger than a skill.

Spec: specs/cli-examples.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>

Author: josealekhine

.context/TASKS.md

@@ -84,14 +84,10 @@ TASK STATUS LABELS:
   accuracy (does the description match behavior?) needs periodic
   LLM audit — not automatable. #priority:medium #added:2026-04-05
 
-- [ ] Create ctx-docstrings skill: audit and fix docstrings
-  against CONVENTIONS.md Documentation section. Skill loads
-  CONVENTIONS.md, scans functions in scope for
-  missing/incomplete docstring sections (Parameters, Returns),
-  reports violations, and optionally fixes them.
-  Language-agnostic design with Go as first implementation.
-  Deterministic enforcement via linter is tracked separately
-  in ideas/spec-convention-enforcement.md
+- [-] Create ctx-docstrings skill: audit and fix docstrings
+  against CONVENTIONS.md Documentation section. Superseded by
+  TestDocCommentStructure compliance test (68 grandfathered).
+  #added:2026-03-20-163413
   #added:2026-03-16-114445
 
 ### Phase -2: Task completion nudge:

internal/audit/doc_structure_test.go

@@ -0,0 +1,140 @@
+//   /    ctx:                         https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package audit
+
+import (
+	"go/ast"
+	"strings"
+	"testing"
+)
+
+// grandfatheredDocStructure is the number of pre-existing
+// doc structure violations. New code must not add to this
+// count. Reduce it as violations are fixed.
+const grandfatheredDocStructure = 68
+
+// TestDocCommentStructure verifies that exported functions
+// with parameters include a "Parameters:" section and
+// functions with return values include a "Returns:" section
+// in their doc comments, per CONVENTIONS.md.
+//
+// Test files and methods with receivers are included.
+// Functions without doc comments are skipped (caught by
+// TestDocComments).
+func TestDocCommentStructure(t *testing.T) {
+	pkgs := loadPackages(t)
+	var violations []string
+
+	for _, pkg := range pkgs {
+		for _, file := range pkg.Syntax {
+			fpath := pkg.Fset.Position(
+				file.Pos(),
+			).Filename
+			if isTestFile(fpath) {
+				continue
+			}
+
+			for _, decl := range file.Decls {
+				fn, ok := decl.(*ast.FuncDecl)
+				if !ok {
+					continue
+				}
+				if !fn.Name.IsExported() {
+					continue
+				}
+				if fn.Doc == nil {
+					continue
+				}
+
+				doc := fn.Doc.Text()
+				hasParams := fnHasParams(fn)
+				hasReturns := fnHasReturns(fn)
+
+				if hasParams &&
+					!strings.Contains(
+						doc, "Parameters:",
+					) {
+					violations = append(
+						violations,
+						posString(
+							pkg.Fset, fn.Pos(),
+						)+": "+fn.Name.Name+
+							" has parameters but"+
+							" missing Parameters:"+
+							" section",
+					)
+				}
+
+				if hasReturns &&
+					!strings.Contains(
+						doc, "Returns:",
+					) {
+					violations = append(
+						violations,
+						posString(
+							pkg.Fset, fn.Pos(),
+						)+": "+fn.Name.Name+
+							" has return values but"+
+							" missing Returns:"+
+							" section",
+					)
+				}
+			}
+		}
+	}
+
+	if len(violations) > grandfatheredDocStructure {
+		t.Errorf(
+			"%d doc structure violations "+
+				"(grandfathered: %d, new: %d):",
+			len(violations),
+			grandfatheredDocStructure,
+			len(violations)-grandfatheredDocStructure,
+		)
+		// Show only the newest violations.
+		start := grandfatheredDocStructure
+		limit := 20
+		if len(violations)-start < limit {
+			limit = len(violations) - start
+		}
+		for _, v := range violations[start : start+limit] {
+			t.Error(v)
+		}
+	} else if len(violations) < grandfatheredDocStructure {
+		t.Errorf(
+			"violations dropped to %d — "+
+				"update grandfatheredDocStructure "+
+				"from %d to %d",
+			len(violations),
+			grandfatheredDocStructure,
+			len(violations),
+		)
+	}
+}
+
+// fnHasParams reports whether fn has at least one
+// named parameter (excluding the receiver).
+func fnHasParams(fn *ast.FuncDecl) bool {
+	if fn.Type.Params == nil {
+		return false
+	}
+	for _, field := range fn.Type.Params.List {
+		for _, name := range field.Names {
+			if name.Name != "_" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// fnHasReturns reports whether fn declares at least
+// one return value.
+func fnHasReturns(fn *ast.FuncDecl) bool {
+	return fn.Type.Results != nil &&
+		len(fn.Type.Results.List) > 0
+}