---
title: Rules and Diagnostics
description: 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](/configuration/#mattpocock1) 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](/check-report/) for report structure, [CLI](/cli/) for streams and exit status, or [Check a repository](/check-a-repository/) for recovery steps.