diff --git a/templates/core/embedded-checks.md b/templates/core/embedded-checks.md index 3888a650..1c342d21 100644 --- a/templates/core/embedded-checks.md +++ b/templates/core/embedded-checks.md @@ -3,57 +3,48 @@ [ID: base-embedded-checks] [DEPENDS ON: templates/core/quality-gates.md] -For a project whose own documents carry runnable checks: context files, -runbooks, rule templates. A reader copies such a check out of the Markdown -and runs it, so it has to survive the copy. +For documents that carry checks a reader copies out and runs: context +files, runbooks, rule templates. ## Extraction [ID: embedded-checks-extraction] -- Never indent a fenced check deeper than the first indentation of its - code; put it flush and point to it from the step -- Prefer a quoted heredoc to an inline `-c` string, and never write the - heredoc opener itself in prose -- Confirm that a line continuation survived into the committed file +- Never indent a fenced check deeper than its code's first indentation; put + it flush and point to it from the step +- Prefer a quoted heredoc to an inline `-c` string +- Never write a heredoc opener in prose +- Confirm a line continuation survived into the committed file - Fold a command onto one line, or bind its parts to shell variables, rather than continue it (SHOULD) -- Extract a check from the committed file and run it before merging the - rule that states it -- Report how many checks a tool could not see, not only how many it ran +- Extract a check from the committed file and run it before merging its rule -Find a check stated outside a fence. It matches over the paragraph, not -the line, because prose wraps: +## Checks + +- Find every check stated outside a fence; the hook matches whole + paragraphs, since prose wraps: ```bash pre-commit run find-unfenced-checks --all-files --verbose ``` -Pass condition: the paragraph count is above zero and the -`checks stated outside a fence` count is zero. Give the hook a `--root` -argument for each directory holding rule documents; a paragraph count of -zero means the roots named nothing, not that the tree is clean. - -Every embedded check MUST compile when extracted the way a reader extracts -it: +- Require paragraphs above zero and `checks stated outside a fence` zero +- Pass a `--root` for each directory of rule documents; zero paragraphs + means the roots named nothing +- Compile every embedded check as a reader extracts it (MUST): ```bash pre-commit run compile-embedded-checks --all-files --verbose ``` -Pass condition: the files-scanned and checks-found counts are above zero -and `checks that do not compile` is zero; each line after the counts names -a check that does not compile. `not applicable` means no Markdown file -holds a heredoc check. - -List the lines where a continuation could be lost. The hook cannot detect -one already lost, so read its list against the source: +- Require files and checks above zero and `checks that do not compile` + zero; each later line names a failing check +- Read `not applicable` as no heredoc check in any Markdown file +- List each line where a continuation could be lost, and read it against + the source; the hook cannot see one already lost: ```bash pre-commit run find-line-continuations --all-files --verbose ``` -Pass condition: it reports the files scanned, the fenced blocks, those in a -check language and the lines among them ending in a continuation, then -lists those lines. A non-zero continuation count is a list to read, not a -failure. +- Read a non-zero continuation count as a list to review, not a failure diff --git a/tests/baselines/template-quality.txt b/tests/baselines/template-quality.txt index 968ad08a..a5b3a9a7 100644 --- a/tests/baselines/template-quality.txt +++ b/tests/baselines/template-quality.txt @@ -21,7 +21,7 @@ templates/backend/webhooks.md 86.9 templates/core/agents.md 100.0 templates/core/config.md 99.3 templates/core/docs.md 99.1 -templates/core/embedded-checks.md 83.6 +templates/core/embedded-checks.md 100.0 templates/core/git.md 89.4 templates/core/measurement.md 95.2 templates/core/oop.md 96.0