docs(adr): record that modelith is not modelled in modelith (ADR-0009)

The self-model is the obvious dogfooding move and the question keeps
coming up. Decide against it: the format's vocabulary already lives in
the schema, the structs, and the schema reference, two of which
TestSchemaStructSync holds in sync. A self-model would be a fourth copy
that nothing checks, and drift between the tool's own model and its own
schema is the worst possible advertisement for it. It would also compete
with examples/ for the worked-example job.

Pinned by TestADR_0009_NoSelfModel: the set of committed *.modelith.yaml
files must be exactly the two known examples. Verified to fail on an
added root-level model, not just to pass on the status quo.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Joe Beda <joe@stacklok.com>

Author: jbeda

internal/model/selfmodel_test.go

@@ -0,0 +1,85 @@
+package model
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// TestADR_0009_NoSelfModel guards ADR-0009: modelith's own domain is not
+// modelled in a *.modelith.yaml. The vocabulary lives in the schema, these
+// structs, and docs/06-schema-reference.md, two of which TestSchemaStructSync
+// holds in sync; a self-model would be a fourth, unchecked copy.
+//
+// The allowlist is the mechanism: a new model file in the repo fails this test
+// until someone adds it here, which puts the ADR in front of them.
+func TestADR_0009_NoSelfModel(t *testing.T) {
+	t.Parallel()
+
+	allowed := map[string]string{
+		"examples/example.modelith.yaml":              "the worked example (golden fixture)",
+		"docs/05-parking-garage/garage.modelith.yaml": "the docs example (golden fixture)",
+	}
+
+	root := repoRoot(t)
+	var found []string
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		// Skip dot-directories: .git, and the gitignored .scratch/ and
+		// .claude/worktrees/, which are full of throwaway fixtures.
+		if d.IsDir() && strings.HasPrefix(d.Name(), ".") && path != root {
+			return fs.SkipDir
+		}
+		if d.IsDir() || !strings.HasSuffix(d.Name(), ".modelith.yaml") {
+			return nil
+		}
+		rel, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		found = append(found, filepath.ToSlash(rel))
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("walking repo: %v", err)
+	}
+	slices.Sort(found)
+
+	for _, rel := range found {
+		if _, ok := allowed[rel]; !ok {
+			t.Errorf("unexpected model file %s\n"+
+				"modelith does not model itself: see project-docs/adr/0009-modelith-is-not-modelled-in-modelith.md.\n"+
+				"If this is a legitimate new example, add it to the allowlist in this test.", rel)
+		}
+	}
+	for rel, why := range allowed {
+		if !slices.Contains(found, rel) {
+			t.Errorf("allowlisted model file %s is missing (%s); update the allowlist if it moved", rel, why)
+		}
+	}
+}
+
+// repoRoot walks up from the test's working directory to the directory holding
+// go.mod.
+func repoRoot(t *testing.T) string {
+	t.Helper()
+	dir, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
+			return dir
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			t.Fatal("could not find repo root (no go.mod in any parent)")
+		}
+		dir = parent
+	}
+}

project-docs/adr/0009-modelith-is-not-modelled-in-modelith.md

@@ -0,0 +1,59 @@
+# modelith is not modelled in modelith
+
+Do not write a `*.modelith.yaml` describing modelith's own domain — the domain
+model format itself. The vocabulary it would capture is already defined in
+three places that tests hold in sync; a self-model would be a fourth copy that
+nothing checks, and it would drift.
+
+## Context
+
+modelith's domain is the domain-model format: entities, attributes,
+relationships, invariants, actions, scenarios, enums, glossary terms. Modelling
+that in modelith is the obvious dogfooding move, and the question comes up
+naturally — most recently while adapting a design-interview skill whose
+upstream version maintains a `CONTEXT.md` glossary.
+
+## Decision
+
+There is no self-model, and no `CONTEXT.md` either. The format's vocabulary
+lives where it already lives:
+
+- `internal/schema/v1/modelith.schema.json` — the normative definition.
+- `internal/model/model.go` — the Go structs, held property-for-property
+  against the schema by `TestSchemaStructSync`.
+- `docs/06-schema-reference.md` — the prose definition users read.
+- `examples/example.modelith.yaml` and `docs/05-parking-garage/` — the worked
+  examples, rendered under `task render-check` and pinned by a golden test.
+
+## Why
+
+- **A fourth copy that nothing checks.** Two of the three definitions are
+  machine-checked against each other. A self-model would join them as prose
+  nobody validates, and drift between a tool's own model and its own schema is
+  the worst possible advertisement for the tool.
+- **It would compete with the worked examples.** `examples/` exists to show what
+  a good model looks like, and it is a golden fixture. A second in-repo model
+  with a stronger claim to being "the real one" muddies which file a newcomer
+  should read, and invites edits made for demo reasons.
+- **The self-referential framing costs more than it teaches.** A model whose
+  `Entity` entity has an `attributes` relationship to an `Attribute` entity
+  reads as a puzzle. Readers learning the format are better served by the
+  parking garage.
+- **Dogfooding still happens, elsewhere.** The format is exercised by real
+  models in other repos, which is where the pressure that produced issues #8–#13
+  and #24–#25 came from. That is the useful kind of dogfooding: a model of a
+  different domain, hitting real gaps.
+
+## Consequences
+
+- `.claude/skills/grill-with-docs/` states this so a design-interview session
+  doesn't helpfully start one; it also drops the upstream skill's `CONTEXT.md`
+  behavior for the same reason.
+- Format vocabulary changes land as one change across the schema, the structs,
+  and the schema reference — never as an edit to a self-model.
+- Pinned by `TestADR_0009_NoSelfModel`, which asserts the set of committed
+  `*.modelith.yaml` files is exactly the known examples. Adding a legitimate
+  new example means extending that list, which puts this ADR in front of
+  whoever does it.
+- Reopen if the format grows a construct that only a self-model can exercise —
+  a concrete gap, not the appeal of dogfooding.