Add integration test for directive rule example fixtures (#274)

* Enforce bad/good/fixed examples for directive rules

Every rule that implements gensection.Directive (MDS019 catalog,
MDS021 include, MDS038 toc, MDS039 build) must ship bad/, good/,
and — when fixable — fixed/ example folders. A new integration test
in internal/integration/directive_examples_test.go walks rule.All()
and fails when any of those folders are missing or when bad/ has a
fix-able entry with no matching fixed/ counterpart. Non-fixable bad
fixtures (cycle detection, build validation) opt out via a
bad/.nofix sentinel file.

Backfills MDS019-catalog/fixed/ so the loop tests the catalog
fix path, and adjusts the MDS019 bad fixture so the post-fix
body satisfies the default-enabled blank-line-around-lists rule.

The markdown-audit skill (.claude/skills/markdown-audit/) now
points at these example folders as the single source of truth
for the <?catalog?> and <?include?> fix recipes. Check 6
(kind without schema) gains an inline-schema vs proto.md
section that links to the four MDS020 example flavors so the
audit reader picks the right shape per kind.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Add pattern/ folders showing authored→directive transformations

The bad/good folders under each rule test diagnostics —
bad/* must fire a diagnostic, good/* must pass all rules.
That layer is the wrong shape for "what does the
hand-maintained anti-pattern look like before someone
adopts this directive?", which is what the markdown-audit
skill needs to show users.

Each directive rule (MDS019 catalog, MDS021 include,
MDS038 toc, MDS039 build) now ships a separate
pattern/bad/ and pattern/good/ pair:

- pattern/bad — the user-authored Markdown someone would
  write today without the directive (hand-maintained
  index, duplicated section, hand-maintained TOC,
  hand-maintained build output snippet).
- pattern/good — the same content rewritten with the
  directive, plus any sibling files the directive needs.

The four directive rule READMEs grew a ## Pattern
section that <?include?>s the new fixtures. A new
directive-rule-readme kind (with proto at
internal/rules/directive-proto.md) layers a stricter
schema over rule-readme that requires that Pattern
section with Without/With subsections. Until kind-schema
composition lands (plan/156_kind-schema-composition.md),
the directive-rule-readme schema duplicates rule-readme's
structure and the four directive READMEs are excluded
from the rule-readme glob so only one schema resolves
per file.

TestDirectiveRulesHaveExamples now also requires
pattern/bad/*.md and pattern/good/*.md for every
gensection.Directive rule. The markdown-audit skill
patterns.md + SKILL.md point at pattern/ as the
canonical before/after pair.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Plan 157: catalog filter by front matter property

Files the use case (a "Directive rules" listing
inside internal/rules/index.md that selects on a
nature property) and the proposed surface (a
where: parameter on the catalog directive that
reuses the CUE expression matcher from
mdsmith list query).

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Inline ## Pattern snippets in directive rule READMEs

Copilot flagged that <?include?> on pattern/bad and
pattern/good rewrote relative link targets so the
displayed paths (e.g. pattern/bad/data/alpha.md)
did not match the source files (data/alpha.md).
The rewrite is stable so mdsmith fix did not flag
the body as stale, but the cosmetic mismatch
confuses a reader trying to copy the snippet
verbatim.

Drop the include directives from the ## Pattern
sections. The snippets in each directive README
now match the source pattern/ files
character-for-character, and the prose points to
pattern/bad and pattern/good as the canonical
folders the integration test still enforces.

Also add bad/.nofix on MDS019 for the new dotdot.md
fixture from main (#275). The dotdot escape is a
validation-only diagnostic with no auto-fix.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Inline ## Examples snippets in MDS019 README

Copilot flagged that the <?include?> for bad/default.md
in the ## Examples section displayed paths with a `bad/`
prefix (`[data/alpha.md](bad/data/alpha.md)`), while the
source fixture uses `[data/alpha.md](data/alpha.md)`.
The displayed body IS what `mdsmith fix` produces — the
include rule's adjustLinks rewrites relative link
targets so they resolve from the host file's directory.
The body is stable, not stale.

But the cosmetic mismatch makes the example misleading,
and the row template `{filename}` placeholder gets the
same rewrite applied. Replace both <?include?> blocks
with inline snippets that match the fixture files
character-for-character; link to good/default.md and
bad/default.md by path for readers who want the source.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Add where: filter to catalog directive

Extend <?catalog?> with a `where:` parameter that
evaluates a CUE expression against each matched file's
parsed front matter, dropping non-matching files before
sort and render. Reuses the matcher from
internal/query/ so the catalog and `mdsmith list query`
accept the same grammar.

Invalid CUE expressions emit an MDS019 diagnostic on
the directive's opening line; missing fields and type
mismatches silently exclude the file, matching
list-query semantics.

Covers tasks 1, 5, and 6 from plan/157.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Add nature key to rule-readme schema and backfill READMEs

Add a required `nature` front-matter key to the rule-readme
schema (internal/rules/proto.md) and the directive-rule-readme
schema (internal/rules/directive-proto.md). The field labels
each rule's kind so the catalog directive can filter listings
by it. Allowed values: directive, generator, content, style,
structure.

Backfill `nature:` on every MDS rule README and add a fixture
under MDS020 (bad/nature-missing.md) that exercises the new
schema requirement.

Covers tasks 2 and 3 from plan/157.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Add Directive rules section to internal/rules/index.md

Uses the new catalog where: filter (plan 157
task 1) and the nature front-matter property
(plan 157 tasks 2 + 3) to surface a filtered
listing of just the four directive rules.

Closes the remaining acceptance criterion in
plan/157.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

* Use catalog where: filter in markdown-audit SKILL

Replace the hand-maintained list of four directive
rule pattern folders with a <?catalog?> directive
that selects every rule README with nature:
directive in its front matter. The list now stays
in sync with the rule catalog automatically — a
new directive rule starts showing up once its
README declares nature: directive.

https://claude.ai/code/session_01K7ZGjbkxFHTdTekshbN3kP

---------

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

Author: jeduden

.claude/skills/markdown-audit/SKILL.md

@@ -116,6 +116,30 @@ fix recipe. When a sibling `patterns.md` is
 present (project install), read it once at the
 start for deeper heuristics and false positives.
 
+For each `<?directive?>` fix, read the rule's
+`pattern/bad/` and `pattern/good/` folders. They
+hold the canonical before/after pair. The list
+below is generated from every rule whose front
+matter declares `nature: directive`, so it stays
+in sync with the rule catalog automatically:
+
+<?catalog
+glob: "../../../internal/rules/MDS*/README.md"
+where: 'nature: "directive"'
+sort: id
+row: "- `internal/rules/{id}-{name}/pattern/` ({name})"
+?>
+- `internal/rules/MDS019-catalog/pattern/` (catalog)
+- `internal/rules/MDS021-include/pattern/` (include)
+- `internal/rules/MDS038-toc/pattern/` (toc)
+- `internal/rules/MDS039-build/pattern/` (build)
+<?/catalog?>
+
+Do not paraphrase directive syntax from memory.
+The integration test
+`TestDirectiveRulesHaveExamples` enforces that
+each pattern folder pair is present.
+
 Do not run `mdsmith check .` from this skill.
 That is the content-lint surface and runs
 separately.

.claude/skills/markdown-audit/patterns.md

@@ -56,17 +56,17 @@ False positives:
 
 Severity: tax.
 
-Fix: replace the block with a `<?catalog?>`
-directive targeting the shared directory.
-
-```markdown
-<?catalog
-glob: "plan/*.md"
-sort: id
-row: "- [{title}](plan/{filename})"
-?>
-<?/catalog?>
-```
+Fix: use a `<?catalog?>` directive on the shared
+directory. Read the canonical before/after pair
+from the rule's own pattern folders:
+
+- before (hand-maintained list): `internal/rules/MDS019-catalog/pattern/bad/`
+- after (catalog directive): `internal/rules/MDS019-catalog/pattern/good/`
+
+These folders are the single source of truth. The
+rule's README `## Pattern` section pulls from
+them. A directive-rule integration test fails
+when they go missing.
 
 Run `mdsmith fix <file>` and confirm the same
 items reappear in the regenerated body.
@@ -143,17 +143,14 @@ False positives:
 Severity: tax.
 
 Fix: extract the shared body into one canonical
-file under `docs/`. Replace each copy with
-`<?include?>`.
-
-```markdown
-<?include
-file: docs/development/index.md
-strip-frontmatter: "true"
-heading-level: "absolute"
-?>
-<?/include?>
-```
+snippet. Replace each copy with `<?include?>`.
+Read the canonical before/after pair from the
+rule's own pattern folders:
+
+- before: `internal/rules/MDS021-include/pattern/bad/`
+  (section duplicated across two files)
+- after: `internal/rules/MDS021-include/pattern/good/`
+  (one snippet plus include directives)
 
 Use `heading-level: "absolute"` when the host file
 needs the included headings to nest under an
@@ -211,27 +208,66 @@ in.
 
 Severity: nice-to-have.
 
-Fix:
-
-1. Create `proto.md` in the kind's primary
-   directory. Copy the shape from an existing
-   `proto.md` in the repo.
-2. Fill the front matter section with required
-   keys and CUE types.
-3. Add a `## <heading>` line per required section.
-4. Wire the schema in `.mdsmith.yml`:
-
-   ```yaml
-   kinds:
-     plan:
-       rules:
-         required-structure:
-           schema: plan/proto.md
-   ```
-
-5. Run `mdsmith check .` and confirm every
-   existing file passes. When a file fails, relax
-   the schema — do not break the files.
+Fix: pick the schema flavor that fits the kind,
+then wire it in `.mdsmith.yml`.
+
+Inline schema vs `proto.md` — when to use which:
+
+- Inline schema in `.mdsmith.yml` when the shape
+  is small (one or two required sections, no
+  nested headings) or the kind exists only in
+  this repo. One source file holds everything.
+- A `proto.md` file when the schema runs more
+  than a screen, the required sections nest, the
+  schema is shared across kinds via
+  `<?include?>`, or the prose around each
+  required field is itself useful documentation.
+  The proto file is itself a lintable Markdown
+  document.
+
+Both flavors satisfy `required-structure`. Do not
+mix the two for a single kind — pick one.
+
+The rule's example folder holds canonical samples
+of each flavor under
+`internal/rules/MDS020-required-structure/good/`.
+Read them before authoring:
+
+- `inline-flat.md` — inline schema with flat
+  required sections.
+- `inline-runbook.md` — inline schema with nested
+  sections and heading aliases.
+- `default.md` plus `data/tmpl.md` — proto file
+  referenced via the `schema:` setting.
+- `schema-compose.md` — proto file composed from
+  shared fragments via `<?include?>`.
+
+Wire-up for inline schema:
+
+```yaml
+kinds:
+  plan:
+    schema:
+      sections:
+        - heading: "Goal"
+          required: true
+        - heading: "Tasks"
+          required: true
+```
+
+Wire-up for proto.md:
+
+```yaml
+kinds:
+  plan:
+    rules:
+      required-structure:
+        schema: plan/proto.md
+```
+
+After wiring, run `mdsmith check .` and confirm
+every existing file passes. When a file fails,
+relax the schema — do not break the files.
 
 ## Check 7 — File placement violation
 

.mdsmith.yml

@@ -258,6 +258,7 @@ ignore:
   - "internal/rules/*/bad.md"
   - "internal/rules/*/good/**"
   - "internal/rules/*/fixed/**"
+  - "internal/rules/*/pattern/**"
   - ".claude/worktrees/**"
   - "editors/**/node_modules/**"
   - "editors/**/dist/**"
@@ -290,6 +291,10 @@ kinds:
     rules:
       required-structure:
         schema: internal/rules/proto.md
+  directive-rule-readme:
+    rules:
+      required-structure:
+        schema: internal/rules/directive-proto.md
   skill:
     path-pattern: "{.claude/skills,editors/claude-code-audit/skills}/{proto.md,*/SKILL.md}"
     rules:
@@ -391,8 +396,25 @@ kind-assignment:
     kinds: [proto]
   - glob: ["plan/*.md"]
     kinds: [plan]
-  - glob: ["internal/rules/proto.md", "internal/rules/MDS*/README.md"]
+  - glob: ["internal/rules/proto.md",
+           "internal/rules/MDS*/README.md",
+           "!internal/rules/MDS019-catalog/README.md",
+           "!internal/rules/MDS021-include/README.md",
+           "!internal/rules/MDS038-toc/README.md",
+           "!internal/rules/MDS039-build/README.md"]
     kinds: [rule-readme]
+  # The four directive rule READMEs need a stricter schema
+  # that requires a Pattern section. Until kind-schema
+  # composition lands (plan/156), the directive-rule-readme
+  # schema duplicates rule-readme's structure and adds the
+  # Pattern requirement, and the four READMEs are excluded
+  # from the rule-readme glob above so only one schema
+  # resolves per file.
+  - glob: ["internal/rules/MDS019-catalog/README.md",
+           "internal/rules/MDS021-include/README.md",
+           "internal/rules/MDS038-toc/README.md",
+           "internal/rules/MDS039-build/README.md"]
+    kinds: [directive-rule-readme]
   - glob: [".claude/skills/proto.md", ".claude/skills/*/SKILL.md",
             "editors/claude-code-audit/skills/*/SKILL.md"]
     kinds: [skill]

PLAN.md

@@ -84,4 +84,6 @@ footer: |
 | 153 | ✅     | opus   | [Unify linkgraph and the LSP symbol index](plan/153_unify-linkgraph-and-lsp-index.md)                                     |
 | 154 | 🔲     | sonnet | [arch-fix: extract cross-rule helpers](plan/154_arch-fix-rule-helper-extraction.md)                                       |
 | 155 | ✅     | sonnet | [arch-fix: relocate convention types out of markdownflavor](plan/155_arch-fix-convention-config-ownership.md)             |
+| 156 | 🔲     | opus   | [Composable required-structure schemas across multiple kinds](plan/156_kind-schema-composition.md)                        |
+| 157 | 🔳     | sonnet | [Catalog filter by front matter property](plan/157_catalog-where-filter.md)                                               |
 <?/catalog?>

docs/guides/directives/generating-content.md

@@ -107,6 +107,34 @@ gitignore: "false"
 ?>
 ```
 
+### Filtering with `where`
+
+The `where` parameter narrows the matched set by a CUE
+expression
+evaluated against each file's parsed front matter. The
+expression grammar is the same one
+[`mdsmith list query`](../../reference/cli/query.md)
+accepts, so a CLI query expression drops in unchanged:
+
+```markdown
+<?catalog
+glob: "internal/rules/MDS*/README.md"
+where: 'nature: "directive"'
+row: "- [{name}]({filename})"
+?>
+<?/catalog?>
+```
+
+The filter runs after globbing and front matter
+parsing, but before sort and render. Failure modes:
+
+- An invalid CUE expression triggers an MDS019
+  diagnostic on the directive's opening line.
+- A file whose front matter is missing the referenced
+  field is excluded (no diagnostic).
+- A field whose value does not satisfy the constraint
+  (wrong type or wrong value) is excluded.
+
 ### Sorting
 
 Format: `[-][numeric:]KEY`. A `-` prefix means

editors/claude-code-audit/skills/markdown-audit/SKILL.md

@@ -120,6 +120,31 @@ fix recipe. When a sibling `patterns.md` is
 present (project install), read it once at the
 start for deeper heuristics and false positives.
 
+For each `<?directive?>` fix, read the rule's
+`pattern/bad/` and `pattern/good/` folders. They
+hold the canonical before/after pair. The list
+below is generated from every rule whose front
+matter declares `nature: directive`, so it stays
+in sync with the rule catalog automatically:
+
+<?catalog
+source-dir: ".claude/skills/markdown-audit"
+glob: "../../../internal/rules/MDS*/README.md"
+where: 'nature: "directive"'
+sort: id
+row: "- `internal/rules/{id}-{name}/pattern/` ({name})"
+?>
+- `internal/rules/MDS019-catalog/pattern/` (catalog)
+- `internal/rules/MDS021-include/pattern/` (include)
+- `internal/rules/MDS038-toc/pattern/` (toc)
+- `internal/rules/MDS039-build/pattern/` (build)
+<?/catalog?>
+
+Do not paraphrase directive syntax from memory.
+The integration test
+`TestDirectiveRulesHaveExamples` enforces that
+each pattern folder pair is present.
+
 Do not run `mdsmith check .` from this skill.
 That is the content-lint surface and runs
 separately.