C4 follow-ons: docs cross-ref audit + persona-name sweep + prettier hooks race fix (3 of 4 from #353)#361
Open
davidlabianca wants to merge 3 commits into
Conversation
…cross-reference audit + any inline drift fixes — closes cosai-oasis#355 All 21 cross-references across the 8 templates verified against the 6 contributing-guide pages; helper text and guides agree on every solicited convention. One trivial drift fixed inline: the iso-22989 placeholder role label in `new_persona.template.yml` and `update_persona.template.yml` was `AI Provider`, which is not a real ISO 22989 role — corrected to `AI Partner`, matching both the template's own helper text and the FM-style-guide §ISO 22989 role-family list. Co-authored-by: AI Assistant <ai-assistant@coalitionforsecureai.org>
…emplates' enumerations) to ADR-021's 8 active personas — closes cosai-oasis#356 Sweeps onboarding-facing copy for ADR-021 canonical-name alignment: README:30 (legacy "Model Creator and Model Consumer" line), new_persona.template.yml:23 (explicit 8-persona list — was using "Platform Provider"/"Model Serving"/"Agentic Provider"/"End User" short forms), new_persona.template.yml:120 ("End User" in the Relationship-to-Existing-Personas e.g.-list), and update_persona.template.yml:60 ("Model Serving" → "AI Model Serving" in the title-rename example). risk-map/yaml/personas.yaml is the source of truth for the 8 active titles. Rendered .github/ISSUE_TEMPLATE/{new,update}_persona.yml regenerate via the pre-commit hook. Co-authored-by: AI Assistant <ai-assistant@coalitionforsecureai.org>
…ests covering both prettier hooks to fix the .git/index.lock race — closes cosai-oasis#357 Root cause: scripts/hooks/precommit/prettier_yaml.py does a per-file `git add` after formatting; under `pre-commit run --all-files` the hook batches into parallel invocations whose concurrent `git add` calls race on .git/index.lock (exit 128, reliably reproducible). require_serial: true collapses the hook into one serial invocation, eliminating the race — empirically verified across 3 consecutive --all-files runs post-fix. prettier-site-assets already carried the property at parity; this commit adds it to prettier-yaml. A new TestRequireSerialPrettierHooks class (scripts/hooks/tests/test_precommit_hook_install.py) asserts the property on both hooks plus the membership invariant, so a future removal from either hook fails CI. Co-authored-by: AI Assistant <ai-assistant@coalitionforsecureai.org>
davidlabianca
added
documentation
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.
C4 follow-ons: docs cross-ref audit + persona-name sweep + prettier hooks race fix (3 of 4 from #353)
Closes #355
Closes #356
Closes #357
Not closed in this PR:
#354(pulled into the ADR-028 tokenizer-re-engineering track) +#353umbrella (stays open until #354 lands).Why three, not four
The #353 umbrella has 4 sub-issues (#354 / #355 / #356 / #357). The first 3 are mechanical infrastructure changes with disjoint files; the 4th (#354 prose-linter enforcement) revealed an architectural-shape problem (detection-by-indexing on a flat token stream — a tree-as-list pattern that won't generalize to deeper ADR-017 D1 rules).
Rather than ship a known-brittle pattern with one more patch, the maintainer pulled #354 into a structural-redesign track.
This PR ships the 3 green sub-issues now. #353 umbrella stays open until #354 lands on its own track.
Commit walk (3 commits)
049b63eAI Provider→AI Partnerin 2 persona templates for ISO 22989 role correctness)6d35d86README:30+new_persona.template.yml:23enumeration +new_persona.template.yml:120example +update_persona.template.yml:60narrative-example (canonicalize toAI Platform Provider/AI Model Serving/Agentic Platform and Framework Providers/AI System Users)0dcb19drequire_serial: trueon bothprettier-yamlANDprettier-site-assetsto close the.git/index.lockself-race (per-filegit add+ parallel workers); drift-prevention tests via newTestRequireSerialPrettierHooksclass; empirical proof: 3× consecutivepre-commit run --all-fileszero failuresReviewer focus
All 3 changes are mechanical with high test coverage. Suggested per-commit walk-through:
049b63e— verify the 21-row audit table in the commit body matches the cross-ref invariants we expect post-Align issue templates with ADRs 016/017/019/021/022 (ADR-026 D4) #344/Align Arm 1 documentation with the post-sweep ADRs 014–022 (Phase C C4) #345. TheAI Provider→AI Partnerfix is the only inline content edit; everything else is a no-op audit.6d35d86— 4 sites: README L30 + 3 template sites. Squashed from 3 commits during authoring. Verify against ADR-021's 8 active persona names.0dcb19d—.pre-commit-config.yamladdsrequire_serial: trueto two hooks + new test class. The 3× consecutive--all-filesproof is the empirical race-closure evidence.Gates (all green at branch tip
0dcb19d)pytest: 2554+ passed / 6 skipped (3 sub-issues added 233 tests collectively).ruff check+ruff format --check: clean.pre-commit run --all-files: clean (infra: prettier-yaml (and prettier-site-assets) hook races itself on .git/index.lock underpre-commit run --all-files#357's race fix validates on the same commit that ships it; 3× consecutive runs zero failures).validate_riskmap.py --force+ control-risk cross-reference validator: clean.ADR cross-refs