Add new msdmd application skills and canon; update docs and indexes - #9
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c9fddf1356
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Every module records its ratios in a `RATIOS` block placed at **both | ||
| boundaries of the file** — the block is the literal first line and the | ||
| literal last line. The file is a self-measuring object; its boundary lines | ||
| carry the measurement, opening and closing. |
There was a problem hiding this comment.
For any real source file, a multi-line msdmd block cannot be both the literal first line and the literal last line. If implementers treat this as one block wrapping the file, normal source lines between the fences are not comment-prefixed metadata and won't satisfy the universal parser; if they treat it as two blocks, the example and wording do not show the trailing duplicate block the runner is supposed to compare. This ambiguity will make consuming ratios_check.py implementations reject otherwise valid modules or implement incompatible placement rules.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Summary
- Reworked
ratios/SKILL.mdsoRATIOSis a compact single-line bookend marker, with the literal first and last lines byte-identical after line-ending normalization. - Replaced the multi-line ratio block schema with a strict single-line schema containing exactly three ordered pairs:
loc_comments,imports_exports, andcalls_definitions. - Made ratio verification self-contained, including boundary-line parsing, byte-identical bookend checks, self-exclusion of the two
RATIOSlines, drift handling, andhmmmhandling. - Removed the absent helper dependency by documenting the canonical
loc_commentscounting rule directly in the skill. - Updated runner and anti-pattern guidance to reject multi-line
RATIOSblocks and require exactly the three canonical ratio pairs. - Updated repo-facing docs and indexes so
ratiosis described as the compact single-line bookend variant rather than a fenced multi-line block. - Committed the changes with commit
cdce023and opened a follow-up PR titled “Repair ratios single-line bookend spec.”
Testing
- ✅
python -m json.tool skills.json >/tmp/skills.json.valid - ✅
git diff --check - ✅
python tools/check_skill_lib_drift.py
There was a problem hiding this comment.
Summary
- Repaired
ratiosto document the requested single-line# === RATIOS === ... === END RATIOS ===bookend repeated as the first and last physical line, with exactly the three ratio pairs and no multi-line duplicate block expectation. ratios/SKILL.mdL28-L57 - Made the
loc_commentscounting rule self-contained and removed reliance on absentscripts/annotate.py/ repo-local# N:Mhelper semantics. ratios/SKILL.mdL93-L109 - Added the propagated pure-stdlib
ratios_check.pyhelper, including compact-line parsing, bookend exclusion, the three ratio computers, drift checking, gap reporting, and--strictbehavior. ratios/ratios_check.pyL19-L30 ratios/ratios_check.pyL81-L178 ratios/ratios_check.pyL181-L255 - Updated distribution/docs references so consumers see that
ratiosnow uses single-line bookends and ships the helper during propagation. README.mdL30 ORG_DISTRIBUTION.mdL28 CLAUDE.mdL42 - Aligned the new skill entries in
skills.jsonwith their frontmatter load-trigger descriptions, including the repairedratiosdescription. skills.jsonL17-L38 skills.jsonL59-L72
Committed changes on the current branch with commit 4fa94dd and created the follow-up PR: “Repair ratios bookends and propagate helper.”
Testing
- ✅
python -m json.tool skills.json >/tmp/skills.json.valid - ✅
python -m py_compile ratios/ratios_check.py - ✅ `tmp=$(mktemp --suffix=.py) && cat > "$tmp" <<'PY'
=== RATIOS === loc_comments=3:1 imports_exports=0:1 calls_definitions=1:1 === END RATIOS ===
"""Example module."""
def add_one(value):
return value + 1
print(add_one(1))
=== RATIOS === loc_comments=3:1 imports_exports=0:1 calls_definitions=1:1 === END RATIOS ===
PY
python ratios/ratios_check.py "$tmp" && rm "$tmp"`
- ✅
python tools/check_skill_lib_drift.py - ✅
python ratios/ratios_check.py --root .
| "path": "doc-build/SKILL.md", | ||
| "kind": "metadata-block", | ||
| "depends_on": ["msdmd"], | ||
| "description": "Self-declaring documentation coverage built on msdmd. Modules declare DOCS blocks; a runner verifies documentation paths and anchors, reports stale or missing docs, and surfaces visible coverage gaps." |
There was a problem hiding this comment.
For consumers that use skills.json instead of walking each SKILL.md (which the repo documents as supported), the new skill descriptions here omit the explicit Load this when ... triggers that are present in the frontmatter. Because harnesses index by description, requests such as auditing module documentation or wiring documentation coverage into CI can fail to select doc-build when loading from the machine-readable index; keep these indexed descriptions aligned with the SKILL frontmatter triggers for the new entries.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
To use Codex here, create a Codex account and connect to github.
There was a problem hiding this comment.
Summary
- Updated
skills.jsonso the indexed descriptions for the new skills include the same explicit load-trigger language as their SKILL frontmatter, including thedoc-build,cap-build,deps-build,owner-build,risk-boundary-build, and repairedratiosentries. - Reworked
ratios/SKILL.mdfrom a multi-lineRATIOSblock spec into the intended compact metadata-line bookend format: one first-line and one last-line comment containing exactly three ordered ratio pairs. - Added the propagated
ratios/annotate.pyhelper so consuming repos receive the counting/checking/updating implementation with theratios/skill directory. - Documented the helper-backed verification contract and made the
loc_commentsrule self-contained, removing reliance on an out-of-tree helper. - Updated repo docs and validation to recognize
ratiosas ametadata-lineskill, clarify helper propagation, and allow the new kind in the drift checker. - Refreshed the existing ratios bookends on the universal Python parser with the new helper.
Testing
- ✅
python -m py_compile ratios/annotate.py tools/check_skill_lib_drift.py msdmd/parsers/universal.py - ✅
python -m json.tool skills.json >/dev/null - ✅
python tools/check_skill_lib_drift.py - ✅
python ratios/annotate.py --check msdmd/parsers/universal.py - ✅
python - <<'PY' ...selected updatedskills.jsondescriptions checked against one-lineSKILL.mdfrontmatter.
Committed changes on the current branch with commit c4d7146 and created the follow-up PR: Repair ratios format and index load triggers.
| The `loc_comments` computer agrees with `scripts/annotate.py` by | ||
| construction — the same counting rule, so a file with a green `# N:M` | ||
| bookend will always produce a matching `loc_comments` value. |
There was a problem hiding this comment.
The loc_comments spec is made to agree with scripts/annotate.py, but this repo does not contain that path (I checked the tree with find/rg), and skill propagation copies only the skill directories plus docs. Consumers implementing ratios_check.py from this canonical skill therefore cannot inspect the referenced algorithm or know what a “green # N:M bookend” means unless they also happen to have the a0p helper; make the rule self-contained here or include the helper in the propagated skill.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
To use Codex here, create a Codex account and connect to github.
There was a problem hiding this comment.
Summary
- Repaired
ratiosso it now defines the intended compact duplicated single-lineRATIOSbookend, with exactly three ratio pairs and explicit non-multi-line parsing guidance. - Made the
loc_commentsrule self-contained and pointed consumers to the propagated helper instead of an absent repo-localscripts/annotate.py. - Added
ratios/scripts/annotate.py, a stdlib-only helper that computes the three ratios, formats/writes bookends, and checks drift for propagated skill consumers. - Updated docs and the index to represent
ratiosas a compactmetadata-bookendand keep the indexed description/load triggers aligned with the revised skill frontmatter. - Updated the drift checker so
metadata-bookendis a valid indexed kind.
Committed the changes on the current branch with commit aa4ca53 and created the PR: Repair ratios bookend spec and propagate helper.
Testing
- ✅
python tools/check_skill_lib_drift.py - ✅
python -m json.tool skills.json >/dev/null - ✅
python -m py_compile ratios/scripts/annotate.py tools/check_skill_lib_drift.py - ✅ `TMP=$(mktemp --suffix=.py); cat > "$TMP" <<'PY'
placeholder
def public():
print('x')
PY
python ratios/scripts/annotate.py --write "$TMP" >/tmp/ratios_line
python ratios/scripts/annotate.py --check "$TMP"
rm "$TMP"`
Co-authored-by: wayseer00 <258336486+wayseer00@users.noreply.github.com>
2 participants
Motivation
canonskill to help agents and maintainers distinguish source-backed doctrine from repo-local practice or guesses.Description
doc-build,cap-build,deps-build,owner-build,risk-boundary-build, andratiosas metadata-block skills andcanonas a procedural skill, each with aSKILL.mddescribing block syntax, field schema, runner contract, reporting shape, and anti-patterns.README.md,AGENTS.md,CLAUDE.md,ORG_DISTRIBUTION.md, andskills.json) to register the new skills, mark which skills define metadata blocks vs. procedural behavior, and clarify that this repo ships universalmsdmdparsers and skill specifications while runner implementations are expected in consuming repos unless a helper script exists in a skill directory.msdmd/SKILL.mdand README prose to list the new application skills and reference them as examples of the universal parser contract.ratiosspec including bookend rule, three ratio computers, and example CLI interface; added runner contracts across the new skills describing required verification and exit behaviors.Testing
skills.jsonto ensure it parses as valid JSON and reflects the new entries.SKILL.mdfiles are well-formed Markdown and that referenced filenames/paths in indexes are consistent.Codex Task