Appendix A - 1. Brief-linting

The Structure of Brief-linting — its shape at a glance:

The linter runs a battery of presence checks over the brief and returns a verdict at the point of no return: pass launches the agent, any failure refuses the dispatch.

flowchart LR
  Brief[/Task brief/] --> Lint{{Brief lint}}
  Reg[(Marker registry)] --> Lint
  Lint -->|all markers present| Launch([Dispatch agent])
  Lint -->|any marker absent| Refuse([Refuse launch, exit 1])

Accessible description: the brief and a registry of required markers both feed a brief-lint gate; when every required marker is present the agent is dispatched, and when any is missing the launch is refused before the agent starts.

Projected from the catalogue entry context-and-dispatch / Brief-linting.

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

Intent

Intent — Statically lint an agent's task brief before the agent is spawned, refusing to launch any brief missing the markers that make the agent's work safe and well-scoped.

Motivation

A brief is the agent's entire world: it is the only instruction set the agent reads before it starts mutating a repository. A brief with a missing marker does not fail loudly. It fails silently and downstream. Omit the worktree-isolation marker and the agent edits main directly, with no fence firing. Omit the dispatch-id and the lifecycle substrate can't track or clean the agent. Omit a mandatory safety snippet (PATH export, commit-cadence, submodule check) and the agent trips a sharp edge 20 minutes in. Because brief authoring is a manual act repeated for every dispatch, the failure is not a one-off; it is a class that recurs on each launch and compounds across a concurrent fleet.

Applicability

• Briefs are structured text with grep-able marker strings, not free prose; the lint's checks are string presence assertions.
• A mandatory-snippet registry the lint can enumerate (see mandatory-snippet-table).
• A dispatch wrapper that calls the lint on the canonical path and refuses to proceed on failure. Otherwise the lint is optional and therefore skipped under time pressure.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The lint reads a registry of required marker strings and asserts each appears in the brief text. It is grep, not parsing — the value is that a malformed brief cannot be dispatched, not that it is unlikely to be. A content check gates on the brief's declared genre, so a citation check fires only on briefs that require the citation.

import sys

REQUIRED_MARKERS = {"isolation: worktree", "dispatch-id:", "subagent-type:"}
GENRE_CHECKS = {
    # brief genre -> markers that genre must additionally carry
    "code": {"cite:file-line", "scope-allowlist:"},
    "doc": set(),
}

def lint_brief(text: str) -> list[str]:
    findings = [f"missing required marker: {m}" for m in REQUIRED_MARKERS if m not in text]
    genre = next((g for g in GENRE_CHECKS if f"brief-genre: {g}" in text), None)
    for m in GENRE_CHECKS.get(genre, set()):        # no genre -> every genre's checks fire (safe default)
        if genre is not None and m not in text:
            findings.append(f"genre '{genre}' brief missing: {m}")
    return findings

if __name__ == "__main__":
    findings = lint_brief(open(sys.argv[1]).read())
    for f in findings:
        print(f"REJECT: {f}")
    sys.exit(1 if findings else 0)   # non-zero = do not launch

Consequences

• Structure is not correctness. The lint checks that a brief is well-formed, not that it is well-scoped: a brief with every marker present can still task the agent with the wrong thing. A green lint buys safety-marker coverage, not a good brief; the human still owns scoping judgment.
• Authoring tax. Every brief must now carry boilerplate markers, making hand-authoring heavier. A brief-template generator mitigates this by pre-placing them by construction. Without the generator the markers become friction the author routes around.
• Each new marker is a maintenance edge. A new mandatory snippet means both a new lint check and threading the marker into the template; drift between the two produces false rejections.
• Bypassable by design. ADA_TOOL_BYPASS_AGENT_FENCE=1 exists for humans; the mechanism's floor is the discipline of not misusing the escape hatch (audit-logged, but still a hole).

Example use within DocAble

• The agent CWD-drift-defense rule: the isolation: "worktree" marker is BLOCKING and lint-verified.
• The dispatch wrapper's prepare step emits its go-ahead only after the brief passes.
• A dedicated check verifies the dispatch-id token and the on-disk marker together, closing the "token present but no live agent" gap.

Related Patterns

• Enabler — mandatory-snippet-table supplies the snippet markers this lint asserts; the registry must exist before the lint can check for them.
• See also (complement) — dynamic-context-injection: the content side of dispatch (injects the rules relevant to the target files) where brief-linting is the structure side (checks the brief is well-formed). Same stage, orthogonal jobs.
• See also (complement) — role-typed-dispatch: the other half of a well-formed dispatch, the role that fixes LLM, isolation, and gate set.