docs: apply config review fixes and declare versioning - #16
Merged
Merged
Conversation
Every repo owns its own markdown config -- the global dot-general/.markdownlintrc fallback was retired (rules/markdownlint.md), so without a repo-local file the .claude/ docs lint against stock defaults and fail on cosmetic table pipes and long table rows. Matches the house settings used by dotfiles and dotagents: MD060 off (pipe alignment is cosmetic churn), MD013 with tables/code_blocks exempt, MD004/MD033/MD041 off, MD024 siblings_only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The release-tag skill reads .claude/CONVENTIONS.md literally for the declared method; the section was in WORKFLOW.md, where it is never found. Its fallback -- infer from `git tag -l` and confirm -- yields nothing here, since the only tag is a lightweight non-semver `end_refactor`. Move the section to its expected home and complete it. git.md *Versioning & tags* requires four things; only method and tag pattern were present. Adds the bump policy (the compatibility surface is the git-notes format, the handle_metadata CLI, and the hook contract), what pushing a tag triggers (nothing in this repo -- no release workflow -- which is exactly the fact that makes the required confirmation cheap), and the unsigned signing posture. v2.0.0 is recorded as the *intended* version, not a committed one; the tag does not land until the modernization is ready to ship. Records as OPEN, for the operator to answer at cut time, whether the line should start at v2.0.0 or at v0.y.z. Tagging v2.0.0 first skips the v0 alpha line, binding strict semver from tag one and crossing the 0 -> 1 stability jump implicitly -- which git.md says must be crossed on purpose, never by accident. Both readings are stated; neither is chosen. Also records that no QA doc and no TESTS.md exist yet, and that no issue tracks them, so the absence reads as a known gap. Relates to #10, #12 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three things. Dedupe prose that restated canonical facts. The branch-protection section listed the rules already in .github/rulesets/protect-master.json and live on GitHub -- three places to update when CI adds required checks. Link the JSON as the record of *what* is enforced and keep only the repo-specific *why* (that required_status_checks is deliberately absent, which the JSON cannot say). Likewise the orchestration section restated the hook mechanics and exemption set from team-managed-delegation.md; keep the half that is genuinely local -- the file-to-role mapping -- and link the rest. Add the ruleset re-apply command and id (20078758), following the precedent in dotfiles' own WORKFLOW.md, so the JSON is actually actionable rather than just a copy on disk. Fix the working-tree read semantics. The text said the team-managed sentinel takes effect "as soon as it lands on master and the checkout is updated" -- which describes default-branch semantics, the very thing the sentence contrasts itself against. It takes effect as soon as the sentinel is on disk, including on the branch that adds it. Fold the deferred sentinels, the deferred protection layers, and the deferred tag ruleset into one table whose cells cite #10, #11, and #12, so the table is a decision record pointing at tracked work rather than a parallel backlog. resolve-task: autonomous now records its real precondition -- a test suite, not merely CI reporting -- and that it too is read from the default branch. Relates to #10, #11, #12 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every other repo in the fleet uses .claude/CLAUDE.md with sibling imports (dotfiles, private_dotfiles, ansible-stuff, bw-serve-client, harleydev, linode-foundation-fabric, mxroute-foundation-fabric, terraform-provider-mxroute); gitperms was the lone root CLAUDE.md with an @.claude/ prefixed import. Adding CONVENTIONS.md meant a second prefixed import, so converge now rather than entrench the odd shape. Claude Code accepts a project CLAUDE.md at either ./CLAUDE.md or ./.claude/CLAUDE.md, and relative @path imports resolve against the directory of the file containing them -- so @WORKFLOW.md and @CONVENTIONS.md resolve inside .claude/. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
harleypig
force-pushed
the
feature/maple-walnut-willow
branch
from
July 31, 2026 02:51
88a8c49 to
0c152ea
Compare
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.
Summary
Applies the config-engineer's review findings on the
.claude/scaffold landed in #9..claude/CONVENTIONS.md—release-tagreads that file literally (SKILL.md:31); it was inWORKFLOW.md, where the skill would never have found it. Its fallback is inferring fromgit tag -l, and this repo's only tag is a lightweight non-semverend_refactor, so inference yields nothing. Now complete againstgit.md's four requirements: method, tag pattern, bump policy, and what pushing a tag triggers (nothing — no release workflow).tracker: github; a.claude/table is a decision record, not a work item.team-managedhook mechanics — three places to update otherwise. Keeps the repo-specific half (whyrequired_status_checksis absent; the file→role mapping) and adds the re-apply command with ruleset id20078758..markdownlint.json—markdownlint.mdhas no global fallback, and the feat: protect master and scaffold repo agent config #9 files already failed (MD060 ×4, MD013 ×2)..claude/CLAUDE.md+ sibling imports, matching the other eight repos in the fleet.The
v0question is deliberately left openTagging
v2.0.0as the first tag skips thev0alpha line entirely, so strict semver would bind from tag one.git.mdsays the 0→1 crossing is "a major decision in its own right… crossed on purpose, never by accident" — and jumping tov2.0.0crosses it implicitly.CONVENTIONS.mdrecords both readings and picks neither, with an explicit instruction not to tag on the agent's own judgment. v2 is in limbo until it is ready; this is answered when the tag is actually cut.Caught during the work
dotagentsis private; this repo is public. Reference-style links togithub.com/harleypig/dotagents/blob/master/rules/…would be dead links for every outside reader and would advertise a private path. Global rules are now referenced bare (`git.md`), matching the existing convention. Standing constraint: do not link dotagents from this repo.Test plan
.claude/CLAUDE.mdimports@WORKFLOW.mdand@CONVENTIONS.md; both resolve against the containing file's directoryCLAUDE.mdremoved; git recorded it as a rename.md, and each commit's tree lints clean independentlyMD013allows 200, so this was checked directly)fixup!/squash!commits survived the autosquashdotagentsreference anywhere in the public treev0decision reads as genuinely undecidedNot done, deliberately
CONVENTIONS.md, not claimed as covered by Complete branch protection once CI exists (required checks + layers 2/3) #10. Needs either an addition to Complete branch protection once CI exists (required checks + layers 2/3) #10 or its own issue..perlcriticrc/.perltidyrcexist at the repo root with nothing running them — wiring that gate is pre-commit/CI work.— agent-authored by Claude