[adoption] ADR require_sections enforcement path is undiscoverable: validate --help and the 1.6 adopt guide never say validate runs it

[chrisdpurcell]

Summary

Nothing in the ADR 1.6 adoption guide or in project-standards validate --help states that project-standards validate is the command that enforces the ADR package's require_sections option. validate --help describes itself purely as the frontmatter/ID/reference validator, so a consumer who enables adr without markdown-frontmatter has no documented reason to believe that command is relevant to ADR structure at all — and can reasonably conclude the option is inert.

Context

• Adoption mode: fresh adoption (Catalog 5, no prior standards authority)
• Project Standards version: 5.29.0, installed from git+https://github.com/L3DigitalNet/project-standards@v5.29.0
• Selected packages: adr (latest -> 1.6) and agent-handoff (latest -> 1.17) only. markdown-frontmatter is deliberately not enabled.
• Relevant option: [standards.adr.config] require_sections = true
• OS / Python: Linux x86_64, Python 3.14.7, installed with uv tool install

What the documentation says

standards/adr/versions/1.6/adopt.md ends its "Author and verify" section with:

project-standards reconcile --check
project-standards validate

followed by "The provider validates structure, not whether prose is semantically well bounded." It does not say which of the two commands runs that provider.

project-standards validate --help says:

Run validate-frontmatter (schema), validate-id (id format), and
validate-references (cross-file, opt-in). All run; the worst exit
code is returned.

ADR section enforcement is not mentioned. docs/usage.md's validate entry likewise describes schema, ID format, and cross-file references only.

Reproduction

With adr enabled at require_sections = true and markdown-frontmatter disabled, add an ADR missing all three required MADR headings:

---
id: 'adr-0001-example-probe'
title: 'Probe ADR deliberately missing required MADR sections'
doc_type: 'adr'
status: 'active'
---

# Probe ADR deliberately missing required MADR sections

Body text only; no MADR headings.

Then run both documented verification commands.

Actual

project-standards reconcile --check — exit 0, reports a fully reconciled control plane and says nothing about the ADR:

OK standards control plane is reconciled

project-standards validate — exit 1, and this is where enforcement actually happens:

docs/adr/adr-0001-example-probe.md: ADR is missing required section: Considered Options
docs/adr/adr-0001-example-probe.md: ADR is missing required section: Context and Problem Statement
docs/adr/adr-0001-example-probe.md: ADR is missing required section: Decision Outcome

✗  3 error(s) across 10 file(s)

Expected

validate --help (and docs/usage.md's validate entry) should disclose that the command also runs the selected package providers' document checks, including ADR structural rules, so the enforcement path for require_sections is discoverable from the command itself. The ADR adoption guide should name validate as the command that enforces the option, rather than listing two commands and leaving the mapping implicit.

Consumer consequence

Non-blocking — the behavior is correct and useful once found — but it is only discoverable by experiment. I established it by writing a deliberately malformed ADR and running both commands to see which one failed. Two concrete risks follow from the gap:

1. A consumer enabling adr without markdown-frontmatter may assume validate is a frontmatter-only command that does not apply to them, skip it, and never enforce require_sections despite having set it to true.
2. A CI job that runs only project-standards reconcile --check as its standards gate — a natural reading, since that is the control-plane command — enforces no ADR structure at all and stays green on a non-conforming corpus.

Suggested resolution

1. Extend the validate help text and its docs/usage.md entry to state that selected package providers contribute document checks, with ADR require_sections / validate_amendments named as an example.
2. In standards/adr/versions/1.6/adopt.md, attribute each verification command — reconcile --check for control-plane state, validate for ADR structural rules — so the option's enforcement path is explicit.

Workaround

Run project-standards validate in CI alongside reconcile --check whenever adr is enabled, regardless of whether markdown-frontmatter is selected.