test: enforce the agent-context contract that review caught it violating (#42)

AGENTS.md told the next agent to keep the file under ~150 lines while
being 165 itself. The stated budget was stricter than the fleet standard
it cites — handbook#68 says "~150 lines, hard cap ~200" — so the file
was the thing that was wrong, not its length. It now states the fleet's
budget.

Nothing could have caught that, which is the real cause: an
agent-context file is followed literally and no test read it. The
conformance test now parses the hard cap out of AGENTS.md and asserts
the file obeys the number it publishes, so the budget can never again
be advice the artifact itself contradicts, and it holds each skill to
the Agent Skills frontmatter contract. Each assertion was proved red by
reintroducing the defect it guards.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: antoinetoussaint-byte

AGENTS.md

@@ -93,7 +93,8 @@ red is the correct outcome and the skip would buy a false green.
 this repo does not pass `Only(...)` to make absence fatal — so
 `TestPythonFastAPILifecycle_Matrix/nix` is the one skip in a green CI run.
 Changing `nixflake.go` or `nix/flake.nix` is unverified by CI: exercise it
-locally with `nix` installed, and say in the PR that you did.
+locally with `nix` installed, and say in the PR that you did. Closing that gap
+is issue #49.
 
 CI installs `uv` and pins `syft` v1.48.0 in `setup-run` so the other halves do
 run. The full skip matrix is in the `lifecycle-test-triage` skill.
@@ -158,8 +159,10 @@ carried here:
   or `ci / build` goes red on a change that passed every other local check.
 - `agent.codefly.yaml` carries the agent version; releases are tag-driven
   (`.github/workflows/releaser.yml`), never hand-built.
-- Keep this file under ~150 lines (hard cap 200). Push depth into a nested
-  `AGENTS.md` beside what it describes, or into `.claude/skills/`.
+- Keep this file near ~150 lines, hard cap 200. Push depth into a nested
+  `AGENTS.md` beside what it describes, or into `.claude/skills/`. The cap and
+  each skill's frontmatter are asserted in `conformance_test.go`, so `go test
+  ./...` enforces them with no workflow change.
 - There is no `CLAUDE.md`. If one is added, it is a one-line `@AGENTS.md`
   pointer — one canonical source, never a second copy to drift.
 - Treat this file as code: the PR that changes a process updates it.

conformance_test.go

@@ -294,3 +294,98 @@ func TestReleaseCanCompileTheCgoTheBinaryNeeds(t *testing.T) {
 			"so CGO_ENABLED=1 has no macOS or cross-linux compiler to use")
 	}
 }
+
+// agentContextCap extracts the line budget AGENTS.md states for itself. The
+// budget is parsed rather than hardcoded so the assertion is that the file
+// obeys its own stated rule: a file that tells the next agent to stay under a
+// number it has itself exceeded is an instruction that reads as false.
+var agentContextCap = regexp.MustCompile(`hard cap (\d+)`)
+
+// skillFrontmatter is the Agent Skills contract: name and description are the
+// only required fields, and the name is what the directory must be called.
+type skillFrontmatter struct {
+	Name        string `yaml:"name"`
+	Description string `yaml:"description"`
+}
+
+func TestAgentContextFilesHonourTheirOwnContract(t *testing.T) {
+	raw, err := os.ReadFile("AGENTS.md")
+	if err != nil {
+		t.Fatalf("read AGENTS.md: %v", err)
+	}
+	lines := strings.Count(string(raw), "\n")
+
+	match := agentContextCap.FindSubmatch(raw)
+	if match == nil {
+		t.Fatal("AGENTS.md does not state a hard cap; the length budget is unenforceable")
+	}
+	stated, err := strconv.Atoi(string(match[1]))
+	if err != nil {
+		t.Fatalf("parse hard cap %q: %v", match[1], err)
+	}
+	if lines > stated {
+		t.Errorf("AGENTS.md is %d lines but states a hard cap of %d; push depth into a skill", lines, stated)
+	}
+
+	// A CLAUDE.md is optional, but when present it must stay a pointer rather
+	// than a second copy that drifts from this file.
+	if pointer, err := os.ReadFile("CLAUDE.md"); err == nil {
+		if strings.TrimSpace(string(pointer)) != "@AGENTS.md" {
+			t.Errorf("CLAUDE.md must be the single line @AGENTS.md, got %q", string(pointer))
+		}
+	}
+}
+
+func TestSkillsDeclareTheRequiredFrontmatter(t *testing.T) {
+	entries, err := os.ReadDir(filepath.Join(".claude", "skills"))
+	if err != nil {
+		if os.IsNotExist(err) {
+			t.Skip("no skills directory")
+		}
+		t.Fatalf("read skills dir: %v", err)
+	}
+
+	valid := regexp.MustCompile(`^[a-z0-9-]{1,64}$`)
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		path := filepath.Join(".claude", "skills", entry.Name(), "SKILL.md")
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			t.Errorf("%s: %v", path, err)
+			continue
+		}
+		// Frontmatter is the block between the leading --- fence and the next.
+		body := string(raw)
+		if !strings.HasPrefix(body, "---\n") {
+			t.Errorf("%s: no YAML frontmatter", path)
+			continue
+		}
+		end := strings.Index(body[4:], "\n---\n")
+		if end < 0 {
+			t.Errorf("%s: frontmatter is not terminated", path)
+			continue
+		}
+		var front skillFrontmatter
+		if err := yaml.Unmarshal([]byte(body[4:4+end]), &front); err != nil {
+			t.Errorf("%s: parse frontmatter: %v", path, err)
+			continue
+		}
+		if front.Name != entry.Name() {
+			t.Errorf("%s: frontmatter name %q does not match directory %q", path, front.Name, entry.Name())
+		}
+		if !valid.MatchString(front.Name) {
+			t.Errorf("%s: name %q must be lowercase letters, digits and hyphens, at most 64 chars", path, front.Name)
+		}
+		// The description is all an agent sees before loading the skill, so an
+		// empty one makes the skill undiscoverable and an over-long one is
+		// rejected by the standard.
+		if front.Description == "" {
+			t.Errorf("%s: description is required", path)
+		}
+		if len(front.Description) > 1024 {
+			t.Errorf("%s: description is %d chars, over the 1024 limit", path, len(front.Description))
+		}
+	}
+}