From ff3813275fd08b080876d8fa353da63d1ced79ca Mon Sep 17 00:00:00 2001 From: Branimir Georgiev <66906831+braboj@users.noreply.github.com> Date: Thu, 22 Oct 2026 00:03:35 +0300 Subject: [PATCH] refactor(git): state each pass condition as a rule The three pass-condition paragraphs and the empty-diff note become rules beside their commands, with the same counts and refusals. Long compound rules split in two. Every MUST and MUST NOT stays. Co-Authored-By: Claude Opus 5.5 --- templates/core/git.md | 64 ++++++++++++++-------------- tests/baselines/template-quality.txt | 2 +- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/templates/core/git.md b/templates/core/git.md index 9ced0f60..57dc4cbf 100644 --- a/templates/core/git.md +++ b/templates/core/git.md @@ -51,14 +51,12 @@ echo "checks not passing: $failing" [ "$watched" -eq 0 ] && [ "$failing" -eq 0 ] ``` -Pass condition: `checks registered` is above zero, `checks not passing` is -zero, and the block exits zero. No check registered after five minutes, or -any failing or cancelled check, exits non-zero and the pull request does not -merge. - -- Re-run a verification a pull request body claims, rather than reading - it, whenever the base has advanced since the body was written; above all - a proof of absence +- Require `checks registered` above zero, `checks not passing` zero and a + zero exit +- Never merge on a non-zero exit: no check registered within five minutes, + or a failing or cancelled check +- Re-run a verification a pull request body claims once the base has moved + since it was written; above all a proof of absence ## Updating a branch @@ -81,27 +79,28 @@ merge. git diff --exit-code --stat -- ``` -Pass condition: no diff, on a zero status. Any output means the committed -artifact does not match its sources. A regenerator that is not idempotent -fails this on a current artifact, which is a generator defect. - -- Put a before-and-after summary of the visible impact in the pull request - body: a verdict matrix, a delta table, a screenshot diff -- Open a tracked follow-up and state the stale files, by name or glob, - where regeneration is too expensive to bundle (MUST) +- Require no diff and a zero status; any output means the committed + artifact does not match its sources +- Treat a regenerator that fails this on a current artifact as defective: + it is not idempotent +- Summarise the visible impact before and after in the pull request body: + a verdict matrix, a delta table, a screenshot diff +- Open a tracked follow-up naming the stale files, by name or glob, where + regeneration is too expensive to bundle (MUST) - Never regenerate a bidirectional artifact, one an ingest or `--apply` - step reads back into the source, from the pipeline it feeds; refresh it - through the step a person owns, and flag it stale + step reads back into its source, from the pipeline it feeds +- Refresh such an artifact through the step a person owns, and flag it + stale - Drop a regenerated file whose diff is whitespace or line endings only: ```bash git diff --ignore-all-space ``` -An empty diff marks the change as noise; `git checkout -- ` drops it. - -- Open every regenerated binary artifact in a viewer, or an image-read - tool, and confirm it tracks its source +- Read an empty diff as noise, and drop the file with + `git checkout -- ` +- Open every regenerated binary artifact in a viewer or an image-read tool, + and confirm it tracks its source - Regenerate a known-current control artifact first; a non-zero diff there means the environment disagrees with the committed files - Pair a spot-check of three to five representative artifacts with one @@ -112,13 +111,13 @@ An empty diff marks the change as noise; `git checkout -- ` drops it. - Declare an Off-limits section in the project's context file, listing the paths that MUST NOT change without explicit approval (MUST) - Offer this default set for the project to cut down: auth and session - code, payment code, database migrations, `.env*` and secret handling, - CI/CD workflows, and the pointer to a vendored rules submodule + code, payment code, migrations, `.env*` and secrets, CI/CD workflows, + and a vendored rules submodule's pointer - Propose a change inside an off-limits path before making it, with a rollback strategy and the tests that would catch a regression (MUST) - Apply the restriction to executable content: steps, commands, flags, - permissions, triggers, pins and a vendored pointer's revision; a diff - confined to prose is ordinary work + permissions, triggers, pins, a vendored pointer's revision +- Treat a diff confined to prose as ordinary work - Treat a comment a tool reads as executable: `# noqa`, `# nosec`, a linter disable, a coverage pragma - Classify by the diff: it is prose only when removing every comment line @@ -130,9 +129,10 @@ An empty diff marks the change as noise; `git checkout -- ` drops it. pre-commit run report-off-limits-paths --hook-stage manual --all-files --verbose ``` -Pass condition: the paths-declared and files-changed counts are above zero. -Each path is a `--path` argument, kept beside the declared list; `--base` -defaults to `origin/main`. Every off-limits line is an escalation to state -in the summary, not a failure. Run it after committing: on the base with a -clean tree it prints `not applicable`, and a base that does not resolve -fails it. +- Require the paths-declared and files-changed counts above zero +- Pass each path as a `--path` argument, kept beside the declared list; + `--base` defaults to `origin/main` +- State every off-limits line in the summary as an escalation; it is not + a failure +- Run it after committing: on the base with a clean tree it prints + `not applicable`, and a base that does not resolve fails it diff --git a/tests/baselines/template-quality.txt b/tests/baselines/template-quality.txt index 968ad08a..18bca12b 100644 --- a/tests/baselines/template-quality.txt +++ b/tests/baselines/template-quality.txt @@ -22,7 +22,7 @@ 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/git.md 89.4 +templates/core/git.md 98.6 templates/core/measurement.md 95.2 templates/core/oop.md 96.0 templates/core/quality-gates.md 92.5