Rules and Diagnostics

Look up stable Rule identifiers, Check Report Operational Diagnostics, and CLI diagnostic codes grouped by operation family.

A Rule identifier belongs to a Violation in evaluated documentation. A diagnostic code identifies an operation that Presswork could not complete. Check Reports contain only Operational Diagnostics from document discovery, document reads, and local-target inspection; other CLI diagnostics occur before a report or in another command.

Markdown destination Rules

Rule identifier	Reported condition
`markdown-destination-malformed`	A Markdown destination cannot be parsed or has an invalid supported-scheme form.
`markdown-destination-scheme-unsupported`	A destination uses a URI scheme other than HTTP, HTTPS, `mailto`, or `tel`.
`markdown-heading-fragment-missing`	A checked Markdown fragment does not match a GitHub heading slug in its target.
`markdown-local-target-case-mismatch`	A local target’s path casing differs from the repository path.
`markdown-local-target-missing`	A local target does not exist.
`markdown-local-target-outside-repository`	A local target escapes the Repository Root lexically or through symbolic links.

Presswork checks links, images, resolved references, CommonMark angle autolinks, GFM literal autolinks, and href or src attributes on raw HTML a and img start tags. Code and unrelated raw HTML are ignored.

Local paths are percent-decoded once and must match repository path casing. Existing files and directories are valid targets. Same-document and cross-document Markdown fragments use GitHub heading slugs, including numeric suffixes for duplicate headings. Fragment comparison is exact after strict percent decoding. Empty and query-bearing destinations are deferred.

Document Type and Template Rules

Rule identifier	Reported condition
`document-type-filename-invalid`	A direct typed-document child does not match its canonical filename pattern.
`template-definition-directive-malformed`	A Template contains an unsupported or malformed Template Directive.
`template-definition-heading-invalid`	A Template’s heading structure is invalid.
`template-definition-optional-placement-ambiguous`	Optional Template boundaries do not identify one valid heading section.
`template-definition-placeholder-malformed`	A Template placeholder does not use the supported identifier form.
`template-definition-prompt-unmatched`	Prompt Template Directive boundaries do not match.
`template-directive-unresolved`	A completed typed document retains a Template Directive.
`template-heading-missing`	A required Template heading is absent.
`template-heading-order`	Template headings appear out of their declared relative order.
`template-heading-structure-invalid`	A completed typed document does not have the required H1 structure.
`template-heading-undeclared`	A Strict Template document contains an undeclared heading occurrence.
`template-placeholder-unresolved`	A completed typed document retains a Template placeholder.

Documentation index Rules

Rule identifier	Reported condition
`documentation-index-directory-missing`	A relevant descendant Documentation Directory lacks its required index.
`documentation-index-document-malformed`	The configured Index Document is not an eligible Recognized Document.
`documentation-index-document-missing`	A required Index Document is absent.
`documentation-index-entry-malformed`	An index inventory entry cannot be classified as a valid member entry.
`documentation-index-member-duplicate`	A relevant member appears more than once in its Index Section.
`documentation-index-member-stale`	An Index Section identifies a member that is no longer relevant.
`documentation-index-member-undescribed`	An index member lacks meaningful authored loading guidance.
`documentation-index-member-wrong-depth`	An entry identifies a member below the direct-child level owned by that index.
`documentation-index-member-wrong-target`	An entry does not target the direct document or child directory index it identifies.
`documentation-index-orphaned-document`	A relevant direct child is absent from its Index Section.
`documentation-index-section-ambiguous`	The Index Section heading appears more than once.
`documentation-index-section-missing`	The Index Section heading is absent.

Enabled Index Policies validate a tree of authored Index Sections without changing them. A relevant child Documentation Directory is represented by a link to its README.md; descendants are reached through that child’s index. Index Documents and direct TEMPLATE.md support files are excluded from their own inventories.

Matt Pocock Profile Rules

Rule identifier	Reported condition
`mattpocock-adr-number-duplicate`	More than one canonical Architecture Decision Record uses the same number.
`mattpocock-adr-number-gap`	The canonical sequence is not contiguous from `0001`.
`mattpocock-adr-status-invalid`	Optional `status` has an unsupported value.
`mattpocock-adr-structure-invalid`	An Architecture Decision Record lacks one H1 and its one-to-three sentence decision paragraph.
`mattpocock-adr-title-slug-mismatch`	The filename slug does not match the H1 title’s normalized slug.
`mattpocock-context-structure-invalid`	`CONTEXT.md` does not match the Profile’s context-language structure.
`mattpocock-context-map-structure-invalid`	`CONTEXT-MAP.md` does not match the Profile’s context-map structure.

Supported Architecture Decision Record statuses are proposed, accepted, deprecated, and superseded by ADR-NNNN.

See the Matt Pocock Profile contract for canonical filenames, document structure, numbering, and context-document requirements.

Check Report Operational Diagnostics

Code	Operation that could not complete
`document-discovery-unavailable`	Git-backed Recognized Document discovery.
`document-read-unavailable`	Reading a Recognized Document or required repository Template.
`target-inspection-unavailable`	Inspecting a local target needed for destination or fragment checking.

These diagnostics make the Check Report incomplete. They include message, path, and recovery fields.

CLI diagnostic codes

Code	Command family	Meaning
`invalid-invocation`	All	Arguments or options do not match the CLI contract.
`repository-root-not-found`	Repository commands	No Repository Root could be discovered.
`invalid-repository-root`	Repository commands	An explicit root is not a valid Repository Root.
`repository-root-unavailable`	Repository commands	Presswork could not inspect the selected root.
`configuration-unavailable`	Repository commands	Present Presswork Configuration could not be read.
`invalid-configuration`	Repository commands	Present Presswork Configuration does not satisfy its strict contract.
`document-type-unknown`	`create`	The requested Document Type is not configured.
`document-type-creation-external`	`create`	The Document Type delegates creation to a named external workflow.
`document-type-creation-manual`	`create`	The Document Type requires manual creation.
`document-creation-field-invalid`	`create`	A supplied field name, value, or `name=value` pair is invalid.
`document-creation-preflight-failed`	`create`	Template, index, temporary-directory, or mutation-path preflight failed.
`document-creation-conflict`	`create`	Another writer or existing destination prevented exclusive creation.
`document-creation-index-stale`	`create`	The Index Document changed before publication.
`document-creation-recovery-required`	`create`	The Index update failed and the created draft was preserved for review.
`document-creation-unavailable`	`create`	A required Template or filesystem operation was unavailable.
`skill-guidance-unavailable`	`skills docs`	Repository-specific guidance could not validate or load required policy.
`internal-error`	All	An unexpected internal failure reached the CLI boundary.

Diagnostics include a message and recovery guidance. Path-related diagnostics also include path. Human diagnostics use labeled lines; --json writes one diagnostic object followed by a newline for commands that accept it. Public diagnostics omit internal causes and stacks.

Use Check Report for report structure, CLI for streams and exit status, or Check a repository for recovery steps.