docs(lint): correct the Vale scalar, size-ceiling and release-gate claims
Four claims in shipped agent-facing docs did not match verified behaviour.
These are read as ground truth by agents in other repos, so each was
reproduced against vale 3.15.2 before rewriting:
- CONTEXT.md and `vale-config/SKILL.md` said both `>` and `|` block scalars
break the description scope. `|` does not — it lints normally and fires every
alert, while `>` yields zero. An agent following the old text would rewrite a
working `|` description into a plain multi-line scalar, which genuinely does
break, inverting the intended remediation. Both now name the forms that do
break and state that `|` does not.
- CONTEXT.md and ADR-0013 described the size hook as failing only above 500
lines, omitting the 2900-word gate it also enforces. Both now describe the
pair and state that `validate.sh` checks the same two.
- ADR-0014 recorded an accepted residual — a wholesale `assets/` deletion going
unflagged — that commit 14c2c91 closed. Left as the point-in-time record and
amended with an update describing the union-with-tag-manifest mechanism,
following the amendment precedent in ADR-0005.
- `vale-config/SKILL.md` asserted a fresh `.vale.ini` fails until `vale sync`
runs, contradicting its own note that built-in styles need no download. The
claim is now scoped to package styles; this repo's two configs declare no
packages and lint clean with zero syncs.
Also repoints AGENTS.md at the seven `gitea:*` skills — the `bin:gitea` route
it named no longer exists.
Refs: #85
This commit is contained in:
@@ -95,8 +95,13 @@ every rule to `level: error` is what actually implements this decision.
|
||||
catch does not pay for a permanent suppression, so the rule is deleted and this ADR's
|
||||
"cherry-picked rules" is one rule, not two.
|
||||
- A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
|
||||
500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. It fails only *above*
|
||||
500 lines, matching `skill-audit/scripts/validate.sh`'s long-standing `<= 500` pass.
|
||||
500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. Both halves of that
|
||||
ceiling are blocking gates, not just the line count: `MAX_LINES=500`, and `MAX_WORDS=2900` as a
|
||||
word-count proxy for the 5,000-token limit (calibrated from this repo's measured ~1.6-1.7 tokens
|
||||
per word — `wc -w` is not BPE tokenization). Either one exceeded fails the hook. Both are
|
||||
inclusive: a file at exactly 500 lines or exactly 2,900 words passes, and only one past a ceiling
|
||||
fails. `skill-audit/scripts/validate.sh` enforces the same pair on the same inclusive terms, so
|
||||
the audit and the commit hook cannot disagree about whether a given `SKILL.md` is over size.
|
||||
- `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
|
||||
future reader doesn't wonder if a trial tier was forgotten.
|
||||
- The styles-portability question — whether `styles/` and `.vale.ini` should move into
|
||||
|
||||
@@ -151,6 +151,20 @@ doesn't wonder if it was overlooked.
|
||||
script now derives the bundle's `assets/` tree from `tokens[0]` instead (double-`dirname`,
|
||||
guarded on the candidate existing and on not resolving to `.`), which is the only derivation
|
||||
compatible with the argument-free `entry:` contract above.
|
||||
- **Accepted residual in the release gate:** deleting a hook's *entire* `assets/` tree is not
|
||||
flagged — the derived candidate path stops existing, so the guard drops it before it reaches
|
||||
the pathspec. Deleting individual files inside a surviving tree is flagged, and tested.
|
||||
- **Accepted residual in the release gate (closed — see the update below):** deleting a hook's
|
||||
*entire* `assets/` tree is not flagged — the derived candidate path stops existing, so the guard
|
||||
drops it before it reaches the pathspec. Deleting individual files inside a surviving tree is
|
||||
flagged, and tested.
|
||||
|
||||
**Update (commit `14c2c91`):** the accepted residual above no longer holds and is recorded here
|
||||
only as the state at the time this ADR was written. `check-release-needed.sh` no longer derives
|
||||
release-relevant paths from the worktree alone. It runs `collect_release_paths` twice — once over
|
||||
the worktree's `.pre-commit-hooks.yaml`, once over the manifest read back from `$LAST_TAG` via
|
||||
`git cat-file -p "$LAST_TAG:$HOOKS_MANIFEST"` — and unions the two path sets, so a path the tag
|
||||
exposed stays in the pathspec even after the worktree's `-d` guard drops it. Wholesale deletion of
|
||||
a hook's bundled `assets/` tree is therefore flagged, and `tests/test-check-release-needed.sh`
|
||||
(case 12) asserts exit 1 for exactly that case. The union does not over-fire: any manifest edit
|
||||
that makes the two disagree already touches `$HOOKS_MANIFEST`, itself a release-relevant path. An
|
||||
unreadable tagged tree (shallow clone, truncated fetch) fails closed rather than silently degrading
|
||||
to worktree-only derivation; a manifest simply absent at the tag — legitimate, it was added since —
|
||||
does not.
|
||||
|
||||
Reference in New Issue
Block a user