Appendix A - 25. Mandatory snippet-table enforcement

The Structure of Mandatory snippet-table enforcement — its shape at a glance:

The table is a registry keyed by snippet, each row carrying an include-when condition and a marker string; the brief lint reads the table and asserts every applicable marker is present.

flowchart LR
  Table[(Snippet registry)] --> Lint{{Brief lint}}
  Brief[/Task brief/] --> Lint
  Lint -->|every required marker present| Pass([Dispatch])
  Lint -->|a required snippet absent| Fail([Refuse launch])

Accessible description: a snippet registry and the task brief both feed the brief lint, which asserts every applicable snippet's marker is present; the dispatch proceeds when all are and is refused when a required snippet is absent.

Projected from the catalogue entry governance-doc-controls / Mandatory snippet-table enforcement.

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — A registry of mandatory agent-brief snippets (PATH export, commit-cadence, worktree discovery, submodule check, …) whose presence is asserted at dispatch by brief-linting, so every dispatched brief carries the safety and context boilerplate it needs.

Motivation

Every dispatch needs certain boilerplate to be safe: the PATH export (or 65+ PDF tests fail for lack of a binary), the commit-cadence discipline, worktree discovery via $(pwd), the submodule check. An author who forgets one ships an agent that trips exactly that sharp edge 20 minutes in. Without a registry of what's mandatory, "which snippets does this brief need" is tribal knowledge that drifts as snippets are added, and the failure recurs on every hand-authored brief.

Applicability

• A snippet registry with grep-able marker strings. The lint asserts marker presence, so each snippet needs a stable marker.
• The snippet bodies themselves, kept verbatim so briefs include the current text.
• An include-when spec so conditional snippets are required only where they apply.
• Brief-linting to do the asserting; this table is inert without its consumer.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The table pairs each snippet with a grep-able marker and an include-when condition; the lint enumerates the required snippets for a given brief and asserts each marker is present. Always-include snippets have no condition; conditional ones fire on the brief's declared shape.

SNIPPET_TABLE = [
    {"name": "path-export",    "marker": "<!-- snip:path -->",      "when": lambda b: True},
    {"name": "commit-cadence", "marker": "<!-- snip:commit -->",    "when": lambda b: True},
    {"name": "submodule-check","marker": "<!-- snip:submodule -->", "when": lambda b: "test/samples" in b},
]

def required_snippets(brief: str) -> list[dict]:
    return [s for s in SNIPPET_TABLE if s["when"](brief)]

def lint_snippets(brief: str) -> list[str]:
    return [f"missing mandatory snippet '{s['name']}' (marker {s['marker']})"
            for s in required_snippets(brief) if s["marker"] not in brief]

if __name__ == "__main__":
    import sys
    findings = lint_snippets(open(sys.argv[1]).read())
    print("\n".join(findings))
    sys.exit(1 if findings else 0)

Consequences

• Verbatim-include means propagation drift. A snippet updated in the registry must be re-pasted into briefs; the marker catches absence, not staleness of the pasted body.
• The table is a maintenance surface. Every new mandatory snippet is a registry row + a lint marker + a template thread; drift among them produces false rejections (shared with brief-linting).
• Over-inclusion bloats briefs. Requiring a snippet where it doesn't apply adds noise the author routes around.

Example use within DocAble

• The agent-snippet include-table (snippet → include-when → marker).
• The brief-lint's marker-presence assertions.
• Always-include snippets (worktree-path, rebase-first) vs conditional ones.

Related Patterns

• Consumer — brief-linting reads this table and asserts each snippet's marker; this registry is brief-linting's enabler (it must exist before the lint can check for its markers).
• See also (sibling) — claude-md-rule-index: another governance document held honest by a hard counterpart, this one via brief-linting rather than a bloat lint.
• See also (family) — doc-hygiene-lints: the broader "documentation enforced by a lint" family.