WIP: extract dev sections and test catalog approaches

Extract coverage gate and file placement from dev index into
separate files. Testing catalog vs static link approaches for
the dev index — catalog glob context shifts when content is
nested via include (see issue discussion).

https://claude.ai/code/session_01J3g8NnEwGYyJWXD1bqtTii

Author: claude

.github/copilot-instructions.md

@@ -27,8 +27,10 @@ row: "- [{summary}](../{filename})"
 - [How generated sections work — markers, directives, and fix behavior.](../docs/background/archetypes/generated-section/README.md)
 - [Shared patterns (archetypes) reused across multiple linting rules.](../docs/background/archetypes/README.md)
 - [Comparison of mdsmith with other Markdown linters and formatters.](../docs/background/markdown-linters.md)
+- [Codecov coverage gate and CI status checks.](../docs/development/coverage.md)
+- [Where to place Markdown files and documentation types.](../docs/development/file-placement.md)
 - [Build commands, project layout, code style, test fixtures, coverage gate, and merge conflicts.](../docs/development/index.md)
-- [PR fixup workflow for rebase, CI monitoring, review comment resolution, and gh CLI setup.](../docs/development/pr-fixup-workflow.md)
+- [Rebase, CI monitoring, and review comment resolution.](../docs/development/pr-fixup-workflow.md)
 - [How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.](../docs/guides/directives/enforcing-structure.md)
 - [How to use catalog and include directives to generate and embed content in Markdown files.](../docs/guides/directives/generating-content.md)
 - [Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.](../docs/guides/directives/hugo-migration.md)
@@ -131,6 +133,19 @@ strip-frontmatter: "true"
 heading-level: "absolute"
 ?>
 Build and test reference for mdsmith contributors.
+See also:
+
+<?catalog
+glob:
+  - "*.md"
+  - "!index.md"
+sort: path
+row: "- [{summary}](../docs/development/{filename})"
+?>
+- [Codecov coverage gate and CI status checks.](../docs/development/coverage.md)
+- [Where to place Markdown files and documentation types.](../docs/development/file-placement.md)
+- [Rebase, CI monitoring, and review comment resolution.](../docs/development/pr-fixup-workflow.md)
+<?/catalog?>
 
 #### Build & Test Commands
 
@@ -194,51 +209,6 @@ When adding or changing a rule feature, add both:
    are discovered automatically by the integration test
    runner in `internal/integration/rules_test.go`.
 
-#### Coverage Gate
-
-Codecov blocks PRs that decrease per-file statement
-coverage. Fork PRs skip the upload and are not gated.
-Three status checks run on same-repo PRs:
-
-- **project** — overall coverage must not drop below
-  the base commit.
-- **patch** — changed lines must have coverage at
-  least equal to the project baseline.
-- **changes** — no individual file's coverage may
-  decrease vs the base commit.
-
-If any check fails, Codecov posts a comment listing
-the affected files with baseline, current, and delta
-percentages. Fix regressions by adding tests for the
-uncovered code paths before merging.
-
-Configuration lives in `codecov.yml` at the repo
-root. The `test` job in `.github/workflows/ci.yml`
-uploads the merged coverage profile to Codecov after
-each run.
-
-To reproduce CI's merged coverage locally:
-
-```bash
-mkdir -p e2e-cover
-E2E_COVERDIR=e2e-cover \
-  go test -covermode=atomic \
-  -coverprofile=unit.cov ./...
-head -1 unit.cov > merged.cov
-tail -n +2 unit.cov \
-  | grep -v 'cmd/mdsmith/' >> merged.cov || true
-tail -n +2 e2e-cover/e2e_coverage.txt \
-  | grep 'cmd/mdsmith/' >> merged.cov
-go tool cover -func=merged.cov
-```
-
-Unit tests cannot cover `cmd/mdsmith/` because those
-functions run in a subprocess. The merge replaces
-those zero-count unit lines with the e2e counts. CI
-performs additional validation (mode header match,
-file existence); see the `test` job in
-`.github/workflows/ci.yml`.
-
 #### Generated Sections
 
 Content between `<?directive ... ?>` and
@@ -256,104 +226,5 @@ mdsmith merge-driver install [files...]
 ```
 
 Run `mdsmith merge-driver install` once per clone.
-
-#### Where to Place Markdown Files
-
-Every Markdown file checked by mdsmith must live in
-one of the allowed directories. The
-`directory-structure` rule (MDS033) enforces this for
-linted files. When creating a new `.md` file, use the
-decision list below — take the **first match**.
-
-##### Decision list
-
-1. **Well-known root file?**
-   (`README.md`, `CLAUDE.md`, `AGENTS.md`, `PLAN.md`)
-   → Place in repo root (`.`)
-
-2. **Plan file?** (has front matter with `id`, `title`,
-   `status` matching plan schema)
-   → Place in `plan/` as `<id>_<slug>.md`
-
-3. **Rule documentation?** (front matter `id` starts
-   with `MDS`)
-   → Place in `internal/rules/<id>-<name>/README.md`
-
-4. **Metric documentation?** (front matter `id` starts
-   with `MET`)
-   → Place in `internal/metrics/<id>-<name>/README.md`
-
-5. **Agent skill?** (SKILL.md with skill front matter)
-   → Place in `.claude/skills/<name>/SKILL.md`
-
-6. **GitHub integration?** (copilot instructions,
-   workflows)
-   → Place in `.github/`
-
-7. **Task-oriented: "how do I...?"** (steps, examples,
-   practical guidance)
-   → Place in `docs/guides/`
-
-8. **Lookup-oriented: "what is the spec?"**
-   (exhaustive, complete, for reference)
-   → Place in `docs/reference/`
-
-9. **Learning-oriented: "teach me"** (sequential
-   tutorial, concrete outcome)
-   → Place in `docs/tutorials/`
-
-10. **Context-oriented: "why?"** (rationale,
-    comparisons, trade-offs, design decisions)
-    → Place in `docs/background/`
-
-11. **Contributor workflow?** (build, test, CI, release
-    procedures)
-    → Place in `docs/development/`
-
-12. **Security analysis?** (audits, threat models)
-    → `docs/security/<YYYY-MM-DD>-<slug>.md`
-    Front matter: `date`, `scope`, `method`.
-    Schema: `docs/security/proto.md`.
-
-13. **Research?** (spikes, experiments, corpus data,
-    not user-facing)
-    → Place in `docs/research/`
-
-14. **Demo fixture?** (VHS terminal recording samples)
-    → Place in `demo/`
-
-15. **Rule test fixture?** (good/bad/fixed examples)
-    → Place in `internal/rules/<id>-<name>/good/`,
-    `bad/`, or `fixed/`
-
-If a file does not match any of these, it does not
-belong in the repo as a standalone Markdown file.
-Consider whether it should be a section in an existing
-document instead.
-
-#### Documentation Types
-
-mdsmith documentation follows four types. Place each
-file in the matching directory:
-
-| Type       | Directory                                 | Purpose                              | Example                             |
-|------------|-------------------------------------------|--------------------------------------|-------------------------------------|
-| Guide      | `docs/guides/`                            | Task-oriented: how to achieve a goal | "How to enforce document structure" |
-| Reference  | `docs/reference/`, `internal/rules/MDS*/` | Lookup-oriented: complete specs      | CLI flags, rule README              |
-| Tutorial   | `docs/tutorials/`                         | Learning-oriented: step-by-step      | "Your first schema"                 |
-| Background | `docs/background/`                        | Understanding-oriented: context      | Comparison with other linters       |
-
-When writing documentation:
-
-- **Guides** answer "how do I...?" — start with a
-  use case, show examples, link to reference for
-  full details
-- **References** answer "what is...?" — complete,
-  accurate, generated where possible (use catalog
-  directives)
-- **Tutorials** answer "teach me..." — sequential
-  steps, minimal prerequisites, concrete outcome
-- **Background** answers "why...?" — context,
-  trade-offs, comparisons, design rationale
 <?/include?>
 <?/include?>

AGENTS.md

@@ -34,8 +34,10 @@ row: "- [{summary}]({filename})"
 - [How generated sections work — markers, directives, and fix behavior.](docs/background/archetypes/generated-section/README.md)
 - [Shared patterns (archetypes) reused across multiple linting rules.](docs/background/archetypes/README.md)
 - [Comparison of mdsmith with other Markdown linters and formatters.](docs/background/markdown-linters.md)
+- [Codecov coverage gate and CI status checks.](docs/development/coverage.md)
+- [Where to place Markdown files and documentation types.](docs/development/file-placement.md)
 - [Build commands, project layout, code style, test fixtures, coverage gate, and merge conflicts.](docs/development/index.md)
-- [PR fixup workflow for rebase, CI monitoring, review comment resolution, and gh CLI setup.](docs/development/pr-fixup-workflow.md)
+- [Rebase, CI monitoring, and review comment resolution.](docs/development/pr-fixup-workflow.md)
 - [How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.](docs/guides/directives/enforcing-structure.md)
 - [How to use catalog and include directives to generate and embed content in Markdown files.](docs/guides/directives/generating-content.md)
 - [Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.](docs/guides/directives/hugo-migration.md)
@@ -138,6 +140,19 @@ strip-frontmatter: "true"
 heading-level: "absolute"
 ?>
 Build and test reference for mdsmith contributors.
+See also:
+
+<?catalog
+glob:
+  - "*.md"
+  - "!index.md"
+sort: path
+row: "- [{summary}](docs/development/{filename})"
+?>
+- [Codecov coverage gate and CI status checks.](docs/development/coverage.md)
+- [Where to place Markdown files and documentation types.](docs/development/file-placement.md)
+- [Rebase, CI monitoring, and review comment resolution.](docs/development/pr-fixup-workflow.md)
+<?/catalog?>
 
 ### Build & Test Commands
 
@@ -201,51 +216,6 @@ When adding or changing a rule feature, add both:
    are discovered automatically by the integration test
    runner in `internal/integration/rules_test.go`.
 
-### Coverage Gate
-
-Codecov blocks PRs that decrease per-file statement
-coverage. Fork PRs skip the upload and are not gated.
-Three status checks run on same-repo PRs:
-
-- **project** — overall coverage must not drop below
-  the base commit.
-- **patch** — changed lines must have coverage at
-  least equal to the project baseline.
-- **changes** — no individual file's coverage may
-  decrease vs the base commit.
-
-If any check fails, Codecov posts a comment listing
-the affected files with baseline, current, and delta
-percentages. Fix regressions by adding tests for the
-uncovered code paths before merging.
-
-Configuration lives in `codecov.yml` at the repo
-root. The `test` job in `.github/workflows/ci.yml`
-uploads the merged coverage profile to Codecov after
-each run.
-
-To reproduce CI's merged coverage locally:
-
-```bash
-mkdir -p e2e-cover
-E2E_COVERDIR=e2e-cover \
-  go test -covermode=atomic \
-  -coverprofile=unit.cov ./...
-head -1 unit.cov > merged.cov
-tail -n +2 unit.cov \
-  | grep -v 'cmd/mdsmith/' >> merged.cov || true
-tail -n +2 e2e-cover/e2e_coverage.txt \
-  | grep 'cmd/mdsmith/' >> merged.cov
-go tool cover -func=merged.cov
-```
-
-Unit tests cannot cover `cmd/mdsmith/` because those
-functions run in a subprocess. The merge replaces
-those zero-count unit lines with the e2e counts. CI
-performs additional validation (mode header match,
-file existence); see the `test` job in
-`.github/workflows/ci.yml`.
-
 ### Generated Sections
 
 Content between `<?directive ... ?>` and
@@ -263,104 +233,5 @@ mdsmith merge-driver install [files...]
 ```
 
 Run `mdsmith merge-driver install` once per clone.
-
-### Where to Place Markdown Files
-
-Every Markdown file checked by mdsmith must live in
-one of the allowed directories. The
-`directory-structure` rule (MDS033) enforces this for
-linted files. When creating a new `.md` file, use the
-decision list below — take the **first match**.
-
-#### Decision list
-
-1. **Well-known root file?**
-   (`README.md`, `CLAUDE.md`, `AGENTS.md`, `PLAN.md`)
-   → Place in repo root (`.`)
-
-2. **Plan file?** (has front matter with `id`, `title`,
-   `status` matching plan schema)
-   → Place in `plan/` as `<id>_<slug>.md`
-
-3. **Rule documentation?** (front matter `id` starts
-   with `MDS`)
-   → Place in `internal/rules/<id>-<name>/README.md`
-
-4. **Metric documentation?** (front matter `id` starts
-   with `MET`)
-   → Place in `internal/metrics/<id>-<name>/README.md`
-
-5. **Agent skill?** (SKILL.md with skill front matter)
-   → Place in `.claude/skills/<name>/SKILL.md`
-
-6. **GitHub integration?** (copilot instructions,
-   workflows)
-   → Place in `.github/`
-
-7. **Task-oriented: "how do I...?"** (steps, examples,
-   practical guidance)
-   → Place in `docs/guides/`
-
-8. **Lookup-oriented: "what is the spec?"**
-   (exhaustive, complete, for reference)
-   → Place in `docs/reference/`
-
-9. **Learning-oriented: "teach me"** (sequential
-   tutorial, concrete outcome)
-   → Place in `docs/tutorials/`
-
-10. **Context-oriented: "why?"** (rationale,
-    comparisons, trade-offs, design decisions)
-    → Place in `docs/background/`
-
-11. **Contributor workflow?** (build, test, CI, release
-    procedures)
-    → Place in `docs/development/`
-
-12. **Security analysis?** (audits, threat models)
-    → `docs/security/<YYYY-MM-DD>-<slug>.md`
-    Front matter: `date`, `scope`, `method`.
-    Schema: `docs/security/proto.md`.
-
-13. **Research?** (spikes, experiments, corpus data,
-    not user-facing)
-    → Place in `docs/research/`
-
-14. **Demo fixture?** (VHS terminal recording samples)
-    → Place in `demo/`
-
-15. **Rule test fixture?** (good/bad/fixed examples)
-    → Place in `internal/rules/<id>-<name>/good/`,
-    `bad/`, or `fixed/`
-
-If a file does not match any of these, it does not
-belong in the repo as a standalone Markdown file.
-Consider whether it should be a section in an existing
-document instead.
-
-### Documentation Types
-
-mdsmith documentation follows four types. Place each
-file in the matching directory:
-
-| Type       | Directory                                 | Purpose                              | Example                             |
-|------------|-------------------------------------------|--------------------------------------|-------------------------------------|
-| Guide      | `docs/guides/`                            | Task-oriented: how to achieve a goal | "How to enforce document structure" |
-| Reference  | `docs/reference/`, `internal/rules/MDS*/` | Lookup-oriented: complete specs      | CLI flags, rule README              |
-| Tutorial   | `docs/tutorials/`                         | Learning-oriented: step-by-step      | "Your first schema"                 |
-| Background | `docs/background/`                        | Understanding-oriented: context      | Comparison with other linters       |
-
-When writing documentation:
-
-- **Guides** answer "how do I...?" — start with a
-  use case, show examples, link to reference for
-  full details
-- **References** answer "what is...?" — complete,
-  accurate, generated where possible (use catalog
-  directives)
-- **Tutorials** answer "teach me..." — sequential
-  steps, minimal prerequisites, concrete outcome
-- **Background** answers "why...?" — context,
-  trade-offs, comparisons, design rationale
 <?/include?>
 <?/include?>