-
Notifications
You must be signed in to change notification settings - Fork 1
skills: guard example-led opt-ins #5
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
650e8d9
skills: guard example-led opt-ins
cheshirecode 8f7a7b2
test: cover example-led opt-in edge cases
cheshirecode 0eabd9a
test: reject fenced worklog opt-in guard
cheshirecode 977cbcb
test: cover tilde-fenced opt-ins
cheshirecode cfc9fd5
fix: parse skill opt-in code fences
cheshirecode bc0e124
fix: detect tab-indented opt-in code
cheshirecode e358cd7
docs: clarify PR handoff readiness
cheshirecode File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,195 @@ | ||
| #!/usr/bin/env python3 | ||
| """Validate compact cross-skill opt-ins.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import argparse | ||
| import pathlib | ||
| import sys | ||
|
|
||
| SKILL_NAME = "example-led-instructions" | ||
| CANONICAL_PREAMBLE = ( | ||
| "For brittle outputs, invoke $example-led-instructions: " | ||
| "0/1/few-shot gate, max 1-3 examples, skip if obvious." | ||
| ) | ||
| CONSUMER_PREAMBLE = ( | ||
| "For brittle outputs, invoke `$example-led-instructions`: " | ||
| "0/1/few-shot gate, max 1-3 examples, skip if obvious." | ||
| ) | ||
| OUTPUT_FIELDS = ( | ||
| "shot_count:", | ||
| "format:", | ||
| "examples_or_skip_reason:", | ||
| "risk_check:", | ||
| "acceptance_test:", | ||
| ) | ||
| WORKLOG_RUNTIME_GUARD = "Do not invoke it for normal `/worklog` runtime." | ||
| FENCE_CHARS = ("`", "~") | ||
|
|
||
|
|
||
| def parse_args() -> argparse.Namespace: | ||
| parser = argparse.ArgumentParser(description=__doc__) | ||
| parser.add_argument( | ||
| "--root", | ||
| default=pathlib.Path(__file__).resolve().parents[1], | ||
| type=pathlib.Path, | ||
| help="repository root to validate", | ||
| ) | ||
| return parser.parse_args() | ||
|
|
||
|
|
||
| def skill_files(root: pathlib.Path) -> list[pathlib.Path]: | ||
| return sorted((root / "skills").glob("*/SKILL.md")) | ||
|
|
||
|
|
||
| def relative(path: pathlib.Path, root: pathlib.Path) -> str: | ||
| return str(path.relative_to(root)) | ||
|
|
||
|
|
||
| def validate_home_skill(root: pathlib.Path, problems: list[str]) -> None: | ||
| skill_md = root / "skills" / SKILL_NAME / "SKILL.md" | ||
| if not skill_md.is_file(): | ||
| problems.append(f"skills/{SKILL_NAME}/SKILL.md: missing") | ||
| return | ||
|
|
||
| text = skill_md.read_text() | ||
| for term in (CANONICAL_PREAMBLE, *OUTPUT_FIELDS): | ||
| if term not in text: | ||
| problems.append(f"{relative(skill_md, root)}: missing {term!r}") | ||
|
|
||
|
|
||
| def strip_bullet(line: str) -> str: | ||
| stripped = line.strip() | ||
| return stripped[2:].strip() if stripped.startswith("- ") else stripped | ||
|
|
||
|
|
||
| def leading_indent_columns(line: str) -> int: | ||
| columns = 0 | ||
| for char in line: | ||
| if char == " ": | ||
| columns += 1 | ||
| elif char == "\t": | ||
| columns += 4 - (columns % 4) | ||
| else: | ||
| break | ||
| return columns | ||
|
|
||
|
|
||
| def fence_marker(line: str) -> tuple[str, int, str] | None: | ||
| if leading_indent_columns(line) > 3: | ||
| return None | ||
| stripped = line.lstrip(" \t") | ||
| if not stripped: | ||
| return None | ||
|
|
||
| marker = stripped[0] | ||
| if marker not in FENCE_CHARS: | ||
| return None | ||
|
|
||
| marker_len = len(stripped) - len(stripped.lstrip(marker)) | ||
| if marker_len < 3: | ||
| return None | ||
| return marker, marker_len, stripped[marker_len:] | ||
|
|
||
|
|
||
| def is_indented_code(line: str) -> bool: | ||
| return leading_indent_columns(line) >= 4 | ||
|
|
||
|
|
||
| def find_mentions(lines: list[str], term: str) -> list[tuple[int, str, bool]]: | ||
| mentions = [] | ||
| active_fence: tuple[str, int] | None = None | ||
| for index, line in enumerate(lines, start=1): | ||
| marker = fence_marker(line) | ||
| line_in_fence = active_fence is not None or marker is not None or is_indented_code(line) | ||
| if term in line: | ||
| mentions.append((index, line, line_in_fence)) | ||
| if marker is None: | ||
| continue | ||
| marker_char, marker_len, marker_suffix = marker | ||
| if active_fence is None: | ||
| active_fence = (marker_char, marker_len) | ||
| elif ( | ||
| marker_char == active_fence[0] | ||
| and marker_len >= active_fence[1] | ||
| and not marker_suffix.strip() | ||
| ): | ||
| active_fence = None | ||
| return mentions | ||
|
|
||
|
|
||
| def validate_reference_line( | ||
| root: pathlib.Path, | ||
| path: pathlib.Path, | ||
| line_number: int, | ||
| line: str, | ||
| in_fence: bool, | ||
| problems: list[str], | ||
| ) -> None: | ||
| rel = relative(path, root) | ||
| stripped = line.strip() | ||
| reference = strip_bullet(line) | ||
|
|
||
| if in_fence: | ||
| problems.append(f"{rel}:{line_number}: $example-led-instructions opt-in is inside a code fence") | ||
| if reference != CONSUMER_PREAMBLE: | ||
| problems.append( | ||
| f"{rel}:{line_number}: $example-led-instructions must use the exact compact opt-in preamble" | ||
| ) | ||
|
|
||
| limit = 180 if rel == "skills/worklog/SKILL.md" else 140 | ||
| if len(stripped) > limit: | ||
| problems.append( | ||
| f"{rel}:{line_number}: example-led opt-in is {len(stripped)} chars; limit {limit}" | ||
| ) | ||
|
|
||
|
|
||
| def validate_consumers(root: pathlib.Path, problems: list[str]) -> None: | ||
| home_skill = root / "skills" / SKILL_NAME / "SKILL.md" | ||
| for path in skill_files(root): | ||
| if path == home_skill: | ||
| continue | ||
|
|
||
| lines = path.read_text().splitlines() | ||
| references = find_mentions(lines, SKILL_NAME) | ||
|
|
||
| if len(references) > 1: | ||
| problems.append( | ||
| f"{relative(path, root)}: duplicate $example-led-instructions opt-in; expected at most one" | ||
| ) | ||
| for line_number, line, line_in_fence in references: | ||
| validate_reference_line(root, path, line_number, line, line_in_fence, problems) | ||
|
|
||
| if path == root / "skills" / "worklog" / "SKILL.md" and references: | ||
| runtime_guards = find_mentions(lines, WORKLOG_RUNTIME_GUARD) | ||
| has_unfenced_runtime_guard = any( | ||
| not in_fence and line.strip() == WORKLOG_RUNTIME_GUARD | ||
| for _, line, in_fence in runtime_guards | ||
| ) | ||
| if not has_unfenced_runtime_guard: | ||
| problems.append( | ||
| f"{relative(path, root)}: example-led opt-in needs unfenced runtime guard: " | ||
| f"{WORKLOG_RUNTIME_GUARD}" | ||
| ) | ||
|
|
||
|
|
||
| def main() -> int: | ||
| args = parse_args() | ||
| root = args.root.resolve() | ||
| problems: list[str] = [] | ||
|
|
||
| validate_home_skill(root, problems) | ||
| validate_consumers(root, problems) | ||
|
|
||
| if problems: | ||
| print("check-skill-opt-ins: FAIL") | ||
| for problem in problems: | ||
| print(f" - {problem}") | ||
| return 1 | ||
|
|
||
| print("check-skill-opt-ins: OK") | ||
| return 0 | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| sys.exit(main()) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please add a red-path fixture for references inside fenced code blocks. The checker reports this case, but the behavior is currently only protected by code review rather than tests.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Addressed in 8f7a7b2 by adding a fenced-code red-path fixture and asserting the checker emits the code-fence failure message. Local validation: ./tests/run.sh all.