#228 chore: tailor .skills/doc-sections; re-sync the shipping fork's Step 1.5 - #229
Merged
Merged
Conversation
…t exist Red: the file is absent, and the shipping fork's Step 1.5 never mentions it. Upstream runs no dead-entry check on advice; this module checks the parts of the prose that can be checked - named paths are tracked, quoted headings exist, every line names a doc - and that the fork introduces both override files doc-check.sh reports on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…Step 1.5 doc-check.sh's advice on a hit was still the python-fastapi defaults (AGENTS.md route table, README quick start) beside archiver's tailored path list. Upstream gregoryfoster/skills#284 ends every such hit with a note naming the untailored half. - .skills/doc-sections routes each watched path at the doc that owns it: CHANGELOG/CONVENTIONS for the trigger, API, SCHEMA, BUS/BUS_CONSUMERS, the dashboard living-docs map, DEPLOYMENT + deploy/README, ARCHITECTURE's layout, and the AGENTS/README doc indexes. Turns the #228 test green. - skills/shipping-work-python-fastapi/SKILL.md: Step 1.5 re-synced from upstream 178ec64 (#261 doc-sections, #284 half-tailoring note, unusable .skills/ is exit 2), plus Step 2's #257 exit-2 note the pinned check-status.sh already implements. synced-from bumped to 178ec64. - docs/SKILLS.md documents the second file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…checked FILE_TOKEN only knew six extensions, so deploy/archiver.service, src/dashboard/static/dashboard.css, .github/workflows/ci.yml and .skills/doc-sensitive-paths were never extracted - the paths the deploy and dashboard lines are likeliest to name could rot silently while the docstring claimed any path was checked. A pinned grammar test now holds the three shapes and the prose that must stay out (e.g., owner/repo). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
deploy/ and scripts/ deliberately over-match tests/deploy/ and tests/scripts/, but no advice line said what to do about such a hit - this branch's own (tests/scripts/test_doc_sections.py) printed eight lines, none applicable, and never named docs/SKILLS.md. The list's "both land on the same docs anyway" was wrong for skill guard tests; it now points at the advice line instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…els/ The line named only src/core/models/, but SCHEMA.md documents invariants enforced in src/core/services/ (registry_announcement, source_revision), src/core/fingerprints.py, src/core/replication/ and the JSON Schema validators; a change there never pointed at it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…omments The heading scan counted every `#` line, including those inside fenced code blocks (README.md's bash comments, CONVENTIONS.md's `# Plain lookup`), so a renamed heading could be satisfied by a comment that happened to contain its text. _headings() now skips fenced code. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
test_doc_sections copied _entries()/_tracked_files() from test_doc_sensitive_paths line for line. Upstream parses both files with one read_list_file so a grammar fix lands on both (#261); two copies here could drift apart and one test would disagree with the script. Both now import read_list_file and tracked_files from tests/scripts/_skills_lists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…d regex "when the diff touches AGENTS.md's changelog trigger regex" read as editing the regex; the trigger is a changed path matching it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2 tasks
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Closes #228.
doc-check.sh(shipping-work Step 1.5) printed the python-fastapi default advice on every hit, beside archiver's tailored path list. Upstream gregoryfoster/skills#284 now ends such a hit with aNote: this project tailors .skills/doc-sensitive-paths but not .skills/doc-sectionsline. This PR commits the second half.Changes
.skills/doc-sections(new): 9 advice lines, each sending a watched path to the doc that covers it. Checked against the docs rather than inferred from doc names. Corrections to the issue's draft:src/. The line points at AGENTS.md's quoted regex and CONVENTIONS.md "Changelog trigger" instead of copying the paths.models/, and the guard teststests/scripts/andtests/deploy/, which the path list deliberately over-matches.tests/scripts/test_doc_sections.py(new): upstream runs no check on the advice (it's prose), so this covers the checkable parts. It fails when a path the advice names is no longer tracked, a quoteddoc "Heading"is gone (code fences skipped), a line names no doc, or the forked SKILL.md doesn't mention both override files. The path grammar is pinned by its own test. It shares one list reader withtest_doc_sensitive_paths.pyviatests/scripts/_skills_lists.py.skills/shipping-work-python-fastapi/SKILL.md(the committed fork): Step 1.5 re-synced from upstream178ec64(#261 doc-sections, #284 half-tailoring note, unusable.skills/exits 2), plus Step 2's #257 exit-2 note, which the pinnedcheck-status.shalready implements.synced-fromis now178ec64.docs/SKILLS.md: documents the second file.No CHANGELOG entry: no trigger path is touched.
Verification
3fb0643(test only) fails 2 tests, ande183407turns them green. The CR round (f63213e..432ef24, one commit per finding) added its own red-first tests for the path grammar and the fence-aware heading scan. Mutations (renamed doc, dead dir, renamed heading, line with no doc) each fail.178ec64doc-check.shrun against this branch prints(advice: .skills/doc-sections)and noNote:line. With the file hidden, the note prints.Issue checklist
.skills/doc-sectionscommitted, naming this repo's docs(advice: .skills/doc-sections)and noNote: this project tailorsline. Verified with the178ec64script; it goes live when the daily SessionStart hook movesskills-vendor/gregoryfoster-skillspast178ec64(pinned at980a0d1today).🤖 Generated with Claude Code