Plan 208: kind files under .mdsmith/kinds/ (#391)

* Plan 208: implement kind files under `.mdsmith/kinds/`

Each YAML file at `.mdsmith/kinds/<name>.{yaml,yml}` now declares
one kind. The basename is the kind's name; the body is the full
`KindBody` (schema, rules, path-pattern, extends). Inline
`kinds.<name>:` in `.mdsmith.yml` stays a first-class source —
projects can mix file-defined and inline kinds freely. The same
name in both is a config error naming both sources so a merged
kind cannot defeat the "read one file to know one kind" property
this surface ships.

`discoverKinds` walks the directory at load time and rejects bad
basenames (`[a-z][a-z0-9-]*`), subdirectories, `.yaml`/`.yml`
extension collisions, and unknown top-level keys (strict
decoding). The merged kind layer threads through `ValidateKinds`
unchanged so the pairwise schema-source mutex and the
`extends:` cycle detector apply uniformly across sources.

Every kind body now carries a `SourcePath` populated by `Load`
(the `.mdsmith.yml` path for inline kinds, the kind-file path
for file kinds). Provenance threads that path through
`LayerEntry.SourcePath` and `ResolvedKind.SourcePath`, and
`mdsmith kinds resolve` / `kinds show` print a `defined-in` line
next to each kind they report. The JSON shape carries
`source-path` on both the body and per-resolved-kind entries.

The repository's own `.mdsmith.yml` migration is deferred:
the pinned `mdsmith` binary this repo lints itself with does
not yet support `.mdsmith/kinds/`. Migration is scheduled for
after the next release bumps the pinned version. Plan 209 is
filed as the follow-up for the parallel
`.mdsmith/conventions/<name>.yaml` slot.

https://claude.ai/code/session_01Ctz5CK1Zhz99xn4RYtmDGn

* Plan 208: cover kind-file error paths and drop dead branch

codecov/patch reported `∅` for the Go component on PR #391 because
the new helpers had uncovered defensive branches that pulled patch
coverage below the project baseline. Close them by either driving
the branch with a test or removing it:

- `mergeKindFiles`: drop the `cfgPath == ""` early return.
  Load is the only caller and always passes a non-empty path.
  CLAUDE.md's "defensive only when you can drive it red/green"
  rule applies here — no test could realistically reach it.
- `discoverKinds`: add tests for the non-IsNotExist ReadDir
  branch (plant a regular file at `.mdsmith/kinds`), the
  non-YAML-extension skip branch (drop a `.md` alongside),
  the YAML anchor/alias rejection branch, and the
  malformed-YAML decode branch. Each test names the offending
  file in the assertion so future refactors keep the
  file-naming contract.
- `parseKindFile`: add a chmod-0000 read-error test. Skips on
  test users (root) where mode-0000 files remain readable;
  CI runs as `runner`, where the branch is exercised.
- `Load`: add a propagation test so a discovery error from a
  bad basename surfaces as the `loading kind files` wrap on
  the Load surface.
- `WriteBodyText` (kindsout): add a failingWriter test for the
  new `defined-in:` line so its error path matches the rest
  of the writer surface.

After these, the three new helpers (`discoverKinds`,
`mergeKindFiles`, `parseKindFile`) hit 100% / 100% / ~91%
(the last branch covered in CI). `WriteBodyText` is back at
100%.

https://claude.ai/code/session_01Ctz5CK1Zhz99xn4RYtmDGn

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

.github/copilot-instructions.md

@@ -109,6 +109,7 @@ row: "- [{summary}](../{filename})"
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](../docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](../docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](../docs/reference/index.md)
+- [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](../docs/reference/kind-files.md)
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](../docs/reference/schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](../docs/reference/section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](../docs/reference/telemetry.md)

AGENTS.md

@@ -115,6 +115,7 @@ row: "- [{summary}]({filename})"
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](docs/reference/index.md)
+- [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](docs/reference/kind-files.md)
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](docs/reference/section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](docs/reference/telemetry.md)

CLAUDE.md

@@ -101,6 +101,7 @@ row: "- [{summary}]({filename})"
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](docs/reference/index.md)
+- [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](docs/reference/kind-files.md)
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](docs/reference/section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](docs/reference/telemetry.md)

PLAN.md

@@ -133,5 +133,6 @@ footer: |
 | 205 | 🔲     |        | [Move extension.ts concerns to wiring.ts](plan/205_arch-fix-extension-ts-srp.md)                                                        |
 | 206 | 🔲     |        | [Document cue/ in architecture layering map](plan/206_arch-fix-cue-types-docs.md)                                                       |
 | 207 | 🔲     | sonnet | [LSP fix preview via ChangeAnnotation](plan/207_lsp-fix-preview.md)                                                                     |
-| 208 | 🔲     | opus   | [Kind-per-file config under `.mdsmith/kinds/`](plan/208_kind-files.md)                                                                  |
+| 208 | 🔳     | opus   | [Kind-per-file config under `.mdsmith/kinds/`](plan/208_kind-files.md)                                                                  |
+| 209 | 🔲     | opus   | [Convention-per-file config under `.mdsmith/conventions/`](plan/209_convention-files.md)                                                |
 <?/catalog?>

docs/development/architecture/cross-system.md

@@ -34,6 +34,7 @@ doc" column says.
 | LSP wire protocol                     | `internal/lsp`                                       | [CLI reference: `lsp`](../../reference/cli/lsp.md)                              | VS Code extension, other editors                           |
 | CLI flags + exit codes                | `cmd/mdsmith`                                        | [CLI reference](../../reference/cli.md)                                         | shell scripts, CI, git hooks                               |
 | `.mdsmith.yml` schema                 | `internal/config`                                    | [Conventions](../../reference/conventions.md)                                   | every project using mdsmith                                |
+| `.mdsmith/kinds/` directory           | `internal/config`                                    | [Kind files](../../reference/kind-files.md)                                     | every project using mdsmith                                |
 | Generated section markers             | `internal/archetype/gensection`                      | [Generated sections](../../background/concepts/generated-section.md)            | every project's Markdown files                             |
 | Claude plugin manifest (published)    | `editors/claude-code/.claude-plugin/plugin.json`     | [Install: Claude plugin](../../guides/install.md)                               | end users via Claude Code marketplace                      |
 | Claude plugin manifest (contributors) | `editors/claude-code-dev/.claude-plugin/plugin.json` | [editors/claude-code-dev/README.md](../../../editors/claude-code-dev/README.md) | mdsmith contributors                                       |

docs/guides/file-kinds.md

@@ -230,6 +230,43 @@ effective kinds:
   - plan (from kind-assignment[2]: glob plan/*.md AND fields-present id)
 ```
 
+## Split a kind into its own file
+
+When a project's `kinds:` block has grown large
+enough that one kind's edits dirty the same
+`.mdsmith.yml` as every other config change, lift
+the kind into a standalone file under
+`.mdsmith/kinds/<name>.yaml`. The basename is the
+kind's name; the body is identical to the inline
+`kinds.<name>:` body.
+
+```yaml
+# .mdsmith/kinds/audit-log.yaml
+schema:
+  frontmatter:
+    title: 'string & != ""'
+    "summary?": 'string'
+  closed: false
+rules:
+  max-file-length:
+    max: 600
+```
+
+The same name in both a file and inline is a
+config error naming both sources, so split a kind
+in one move rather than leaving both copies
+behind. Names stay stable, so `kind-assignment:`
+entries that referenced the inline kind keep
+working with no edit.
+
+`mdsmith kinds resolve <file>` and `mdsmith kinds
+show <name>` print the defining-source path next
+to each kind so a mixed configuration stays
+auditable. See the
+[kind files reference](../reference/kind-files.md)
+for the full layout, basename rule, and JSON
+shape.
+
 ## Schema inheritance with `extends`
 
 A kind can build on another kind's schema via the `extends:` key.

docs/reference/index.md

@@ -36,6 +36,7 @@ row: "- [{summary}]({filename})"
 - [Print the mdsmith build version and exit.](cli/version.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](globs.md)
+- [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](kind-files.md)
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](telemetry.md)

docs/reference/kind-files.md

@@ -0,0 +1,139 @@
+---
+title: Kind files under `.mdsmith/kinds/`
+weight: 25
+summary: >-
+  Each file under `.mdsmith/kinds/` declares one
+  kind. The basename is the kind name; the file body
+  carries the full `KindBody` — schema, rules,
+  `path-pattern:`, `extends:`. Sits alongside inline
+  `kinds.<name>:` in `.mdsmith.yml`.
+---
+# Kind files under `.mdsmith/kinds/`
+
+A **kind file** is a YAML file under
+`.mdsmith/kinds/` whose basename is the kind's name
+and whose body is the full kind definition. One file
+per kind, no nesting. The directory sits next to
+`.mdsmith.yml` at the workspace root.
+
+```text
+.mdsmith.yml                   # unchanged
+.mdsmith/
+  kinds/
+    audit-log.yaml
+    secret-rotation.yaml
+    architecture-doc.yaml
+```
+
+Use kind files when the `kinds:` block has grown
+large. Each rule edit dirties the same
+`.mdsmith.yml` as every other config change.
+Splitting kinds into one file each isolates the
+history. The read path shortens too: open
+`audit-log.yaml` to see the whole `audit-log`
+kind.
+
+## File shape
+
+The file body matches the inline
+`kinds.<name>:` body. It accepts every
+[`KindBody`](../guides/file-kinds.md) key:
+`extends:`, `path-pattern:`, `categories:`,
+`schema:`, `rules:`. A key outside that set is
+a config error.
+
+```yaml
+# .mdsmith/kinds/audit-log.yaml
+schema:
+  frontmatter:
+    title: 'string & != ""'
+    "summary?": 'string'
+    audit-from: '=~"^[0-9a-f]{7,40}$"'
+  filename: "architecture-audit.md"
+  closed: false
+  sections:
+    - heading: null
+    - heading:
+        regex: '.+'
+        repeat: { min: 0 }
+rules:
+  max-file-length:
+    max: 600
+```
+
+## Basename rule
+
+The kind's name is the basename minus extension.
+The basename must match `[a-z][a-z0-9-]*` — lower
+case, starting with a letter, with optional
+hyphen-separated segments. The rule applies only to
+filenames (OS case folding, path safety); inline
+`kinds.<name>:` keys stay unvalidated.
+
+Both `*.yaml` and `*.yml` are scanned. Two kind
+files with the same basename across the two
+extensions is a config error naming both files.
+
+Subdirectories under `.mdsmith/kinds/` are
+rejected. One kind per file, flat layout.
+
+## Composition with `.mdsmith.yml`
+
+`kinds.<name>:` blocks inside `.mdsmith.yml`
+remain a first-class source. A project can mix
+inline and file-defined kinds freely.
+
+The same kind name declared in **both** a file and
+inline is a config error naming both sources. The
+two sources do **not** merge — a merged kind would
+defeat the "read one file to know one kind"
+property kind files ship.
+
+`kind-assignment:`, `overrides:`, and `ignore:` are
+glob-keyed and stay in `.mdsmith.yml`. A
+kind-assignment entry references a kind by name —
+inline or file kind — with no extra wiring.
+
+## Schema sources
+
+A kind file accepts the same three schema sources
+as an inline kind, and they remain mutually
+exclusive (acceptance criterion #6 of plan 208):
+
+- inline `schema:` block
+- `rules.required-structure.schema:` path to a
+  `proto.md`
+- legacy `rules.required-structure.inline-schema:`
+  map
+
+Setting two on the same kind errors at config load
+with both source names.
+
+A schema shared across kinds is shared via
+`extends:` — the inheritance chain works
+seamlessly across sources. A file kind may extend
+an inline kind and the reverse. The cycle detector
+runs on the merged kinds map.
+
+## Audit
+
+`mdsmith kinds resolve <file>` prints the
+defining-source path next to each kind it
+reports. A mixed resolution shows the path each
+kind came from. You can jump straight to the
+right file:
+
+```text
+file: docs/audit.md
+effective kinds:
+  - audit-log (from kind-assignment[3]: glob docs/**/*.md) defined-in .mdsmith/kinds/audit-log.yaml
+```
+
+`mdsmith kinds show <name>` adds a `defined-in:`
+line to the body output, so the same info is
+available without going through a target file.
+
+The JSON shape (`--json`) carries a
+`source-path:` key on each kind body and on every
+resolved-kind entry so editor integrations can
+key off a stable field.

internal/config/config.go

@@ -155,6 +155,14 @@ type KindBody struct {
 	// sections. A cycle in the extends chain (single- or multi-hop)
 	// is reported by ValidateKinds. See plan 135.
 	Extends string `yaml:"extends,omitempty"`
+
+	// SourcePath is the workspace-absolute path of the file that
+	// defined this kind — either `.mdsmith.yml` for inline kinds
+	// or `.mdsmith/kinds/<name>.{yaml,yml}` for file-defined kinds
+	// (plan 208). Not serialized to YAML; populated by Load.
+	// Provenance surfaces it as `kinds.<name> (<path>)`; CLI
+	// resolve/show prints it next to each kind.
+	SourcePath string `yaml:"-"`
 }
 
 // KindAssignmentEntry assigns one or more kinds to files matching the