docs: define the framework content normalization standard by mattaereal · Pull Request #561 · security-alliance/frameworks

mattaereal · 2026-07-26T23:11:13Z

Summary

Defines repository-wide content normalization standards without rewriting framework pages.

Existing guidance reviewed

AGENTS.md (agent workflow; partially duplicated and conflicted with the page template)
docs/pages/contribute/contributing.mdx (human workflow + partial style notes)
docs/pages/config/template.mdx (executable skeleton; strongest structural source)
SKILL.md (retrieval only — left unchanged in purpose)
README.md, vocs.config.ts, package.json, justfile, .markdownlint.json, cspell.json
Generators: indexes, tags, printables, certs, sitemap, llms, searchbar
Canonical overview example: docs/pages/supply-chain/overview.mdx
Live develop llms.txt inventory and baseline local build

Gaps and contradictions found

No explicit page-type taxonomy — overviews, runbooks, cert controls, templates, and guides were forced toward one mental mold without exception rules.
AGENTS.md vs template — agents were told to use separate “Pitfalls / cheat sheet” sections; the template forbids generic pitfalls dumps and defines a different opening sequence.
Key Takeaway — required in the template but missing or non-canonical on most live pages; no single enforce-able label.
No modality contract — must / should / may undefined; “we recommend / consider / where possible” common.
No terminology table — Web3, multisig, OpSec, allowlist, on-chain variants drift across frameworks.
No objective validator — only cspell + markdownlint; structure and chrome unchecked.
Exception mechanism missing — certs, pure templates, and process docs cannot honestly use the same required sections.

Authority map (now)

Concern	Authoritative source
Agent commands / generated-file rules	`AGENTS.md`
Human workflow, sidebar, images, signed commits	`docs/pages/contribute/contributing.mdx`
Page types, sections, overview maps, exceptions	`docs/pages/contribute/content-model.mdx` (new)
Voice, modality, terminology	`docs/pages/contribute/style-and-terminology.mdx` (new)
Executable skeleton	`docs/pages/config/template.mdx`
Normalization PR checklist	`docs/pages/contribute/docs-normalization-checklist.mdx` (new)
Objective structure checks	`pnpm run validate:content` → `utils/validate-content.cjs` (new)
Retrieval-only agents	`SKILL.md`

Page types defined

Framework overview; conceptual explanation; procedure/implementation guide; operational playbook; IR runbook; checklist; reference/catalog; reusable template; case study; certification criteria; project/contribution docs.

Rules suitable for automation

Frontmatter presence/length bands, required chrome components, canonical Key Takeaway label, heading skips, static checkbox detection, overview page-map heading presence, H2 count soft limit. Exposed as non-strict by default (--strict optional) so migration is not a CI hard-fail on historical debt.

Rules that remain reviewer judgments

Technical accuracy, takeaway insight quality, citation fitness, when to split pages, substantive cross-framework conflicts, exception approval.

Migration strategy

Merge this PR (standards only).
One framework-scoped PR per domain from latest origin/develop.
Reorganize supported prose; do not invent security guidance; call out expert gaps.
Never hand-edit generated index.mdx or llms artifacts.

Generator / LLM compatibility

Sidebar entries added with dev: true. Build regenerates indexes/LLM/search from sidebar; no hand-edited generated files in this PR.

Validation

Signed commit verified (git log --show-signature)
cspell clean on new/changed contribution docs
markdownlint-cli2 clean on new content-model docs
pnpm run docs:build passed (pre-existing slot warning OutlineFooter only)
pnpm run validate:content -- --path docs/pages/contribute — new pages pass; pre-existing contribute pages still show baseline debt
Diff limited to standards, template/AGENTS pointers, validator, sidebar, wordlist
No framework content rewritten

Baseline inventory (develop)

~369 content MDX pages / ~32 frameworks-or-families
Automated audit: 289 pages missing Key Takeaway; 365 pages with ≥1 structural signal
Baseline: cspell OK on docs/pages; docs:build OK; markdownlint has pre-existing failures (concentrated in physical-security, community-management, governance)
just lint wrapper requires host markdownlint-cli2 (not a package dependency today)

Framework normalization follow-ups

Separate PRs will target develop and reference this PR. No repository-wide content rewrite.

Test plan

Review content-model + style pages on CF preview
Confirm Contributing sidebar shows new dev: true entries on .dev only
Spot-check pnpm run validate:content -- --path docs/pages/supply-chain
Confirm no framework page body changes in this diff

Add content model, style/terminology guide, normalization checklist, and objective validate:content checks. Point AGENTS.md and the page template at a single ownership map without rewriting framework pages.

github-actions · 2026-07-26T23:11:23Z

Sidebar Configuration Reminder

This PR includes added, renamed, or removed documentation files:

docs/pages/contribute/content-model.mdx (added)
docs/pages/contribute/docs-normalization-checklist.mdx (added)
docs/pages/contribute/style-and-terminology.mdx (added)

Please ensure that:

The sidebar in vocs.config.ts has been updated to include these files
New content has the dev: true parameter so it's marked as under development
Sidebar links match the file paths - use the preview deployment to verify

See Contributing Guide – Sidebar & Navigation for more details.

_{This is an automated reminder. If this PR doesn't need sidebar changes, you can ignore this message.}

cloudflare-workers-and-pages · 2026-07-26T23:14:34Z

Deploying frameworks with Cloudflare Pages

Latest commit:	`baf9785`
Status:	✅ Deploy successful!
Preview URL:	https://f690005f.frameworks-573.pages.dev
Branch Preview URL:	https://docs-content-normalization-s.frameworks-573.pages.dev

View logs

Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview.

Neutralize fence comments that look like headings, canonicalize overview page-map titles, clamp descriptions, demote excess H2s, and mark template pages with content-model exceptions.

* docs(encryption): normalize structure and wording Add Key Takeaways, page map, contributors metadata, and further reading across Encryption pages while preserving existing control guidance. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * fix: remove multiple lines descriptions as it breaks the build * docs(encryption): align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case section headings; move soft descriptions into the preferred 140–160 band. --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

* docs(user-team-security): normalize stub structure and navigation Replace empty headings with stub pages, Key Takeaways, maps to Awareness, and register the framework in the sidebar as development content. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs(user-team-security): use canonical overview page-map heading Rename "What this framework will cover" to "What this framework covers" so validate:content recognizes the page map under the updated #561 rules. * docs(user-team-security): tighten overview description to preferred band Drop one word so the stub overview description sits in the 140–160 preferred range from the content model.

* docs(threat-modeling): normalize structure and wording Expand the overview, add Key Takeaways and further reading, and attach contributor metadata while preserving STRIDE-oriented guidance. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs(threat-modeling): sentence-case H2s and trim redundant intros Collapse multiline descriptions, fix heading case to match the content model house style, and drop leftover generic intro paragraphs already covered by Key Takeaways. * docs(threat-modeling): fix sidebar label for identify-and-mitigate page Align vocs.config text with the page title "Identify and Mitigate Threats" (was the truncated "Identity Mitigate Threats").

* docs(vulnerability-disclosure): normalize structure and wording Add Key Takeaways, contributors, page map, related frameworks, and Further reading. Editorial cleanup only; no new security controls. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs(vulnerability-disclosure): clarify triage wording and desc punctuation Replace an awkward triage bullet on the overview and terminate the bug bounties description with a period for consistent frontmatter style. * Update docs/pages/vulnerability-disclosure/overview.mdx * Update docs/pages/vulnerability-disclosure/security-contact.mdx

* docs(security-automation): normalize structure and wording Add Key Takeaways, contributors, overview page map, related frameworks, and Further reading. Editorial cleanup only; no new security controls. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs(security-automation): complete overview desc and sentence-case Further reading Finish a truncated overview description and align further-material H2s with the preferred sentence-case catalog label (Further reading).

…standard Applies the standard introduced in security-alliance#561 and the sentence-case heading rule from security-alliance#595: - Renames 'Further Reading & Tools' to 'Further reading' on all four pages - Renames the overview's page map section to 'What this framework covers' - Moves three Rego comments into the surrounding prose The last change is a workaround rather than an improvement. utils/validate-content.cjs extracts headings without stripping fenced code, so a line-start '#' comment inside a Rego block parses as an H1 and any following H3 is reported as heading_level_skip. Noted on the PR. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx

* docs(iam): normalize structure and wording Add Key Takeaways, foundations, page map, contributors, and further reading across the IAM framework without inventing new access-control products. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs(iam): polish description frontmatter and RBAC wrap Collapse multiline YAML descriptions to single lines for stable length checks, and fix an awkward line break in the RBAC role definition example.

* docs(community-management): normalize structure and wording Add Key Takeaways, canonical page map, related frameworks, Further reading, and markdownlint-clean tables/line wraps. Preserve existing contributors and guide deep-link structure; no new security controls. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings.

* docs(awareness): normalize structure and wording Canonical Key Takeaways, overview page map without .mdx links, related frameworks, and full contributors roles. Editorial only; body content retained. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs: add Further Reading sections for validate:content Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview. * remove multiple blank lines to remove linter errors * Expand further reading section --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

) * docs(secure-software-development): normalize structure and wording Add Key Takeaways, contributors, overview page map, related frameworks, and Further reading. Fix truncated intro on threat-modeling page. Editorial only; no new security controls. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings.

* docs(safe-harbor): normalize structure and wording Add Key Takeaways, page map, related frameworks, and contributor roles. Preserve legal/process content without substantive rewrite (steward-owned). * docs(safe-harbor): fix emphasis style for markdownlint * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: add Further Reading sections for validate:content Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview. * docs(safe-harbor): reduce overview H2 count for validate:content * expand further reading sections --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

* docs(dprk-it-workers): normalize structure and wording Add Key Takeaways, overview page map and related frameworks, normalize contributor frontmatter. Preserve TTP and mitigation body content. * docs(dprk-it-workers): wrap Key Takeaways for markdownlint * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs: add Further Reading sections for validate:content Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview. * expand further reading sections --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

* docs(ens): normalize structure and wording Canonical Key Takeaways on all pages, overview related frameworks and Further reading, complete contributor roles. Preserve ENSIP guidance bodies. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs: add Further Reading sections for validate:content Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview. * Expand further reading sections --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

* docs(security-testing): normalize structure and wording Add Key Takeaways across pages, tighten overview page map and related frameworks, fix mutation-testing heading chrome. Preserve deep technical bodies; editorial only. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs(security-testing): fix heading skip and H2 count for validate:content Avoid bash comments that the validator treats as markdown H1s. Demote extra mutation-testing H2s so the page stays within the soft H2 budget. * Update docs/pages/security-testing/unit-testing.mdx Co-authored-by: Sara Russo <sararusso984@gmail.com> * Fix formatting and update coverage command in docs --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

* docs(privacy): normalize structure and wording Add Key Takeaways across privacy and VPN pages, overview page map with nested VPN children, related frameworks, and contributor roles. * docs: drop invented contributor credits Match develop authorship exactly. Clear wrote/reviewed/fact-checked arrays where normalization invented authors on pages that had none. Do not attribute chrome-only edits as content authorship. * docs: clamp descriptions to 120–170 content band Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes. * docs: align further-reading headings with validate:content Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings. * docs: add Further Reading sections for validate:content Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview. * docs(privacy): use canonical page-map heading on VPN overview * Expand further reading sections --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>

docs: define the framework content normalization standard

a28e9e5

Add content model, style/terminology guide, normalization checklist, and objective validate:content checks. Point AGENTS.md and the page template at a single ownership map without rewriting framework pages.

mattaereal added a commit that referenced this pull request Jul 27, 2026

docs: add Further Reading sections for validate:content

dd08aa8

Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview.

mattaereal added a commit that referenced this pull request Jul 27, 2026

docs: add Further Reading sections for validate:content

42ed9d3

Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview.

mattaereal added a commit that referenced this pull request Jul 27, 2026

docs: add Further Reading sections for validate:content

85fcb32

Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview.

mattaereal mentioned this pull request Jul 27, 2026

docs(contribute): require sentence-case headings including catalog labels #595

Merged

3 tasks

s1ns3nz0 mentioned this pull request Jul 27, 2026

docs(devsecops): add Policy as Code section #592

Merged

3 of 9 tasks

scode2277 added the enhancement Updates that improve or refine existing features, user experience, or system performance. label Jul 28, 2026

Navigation Menu

Repository navigation

docs: define the framework content normalization standard - #561

docs: define the framework content normalization standard#561
mattaereal merged 3 commits into
developfrom
docs/content-normalization-standard

mattaereal commented Jul 26, 2026

Uh oh!

github-actions Bot commented Jul 26, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

mattaereal commented Jul 26, 2026

Summary

Existing guidance reviewed

Gaps and contradictions found

Authority map (now)

Page types defined

Rules suitable for automation

Rules that remain reviewer judgments

Migration strategy

Generator / LLM compatibility

Validation

Baseline inventory (develop)

Framework normalization follow-ups

Test plan

Uh oh!

github-actions Bot commented Jul 26, 2026

Sidebar Configuration Reminder

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying frameworks with Cloudflare Pages

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cloudflare-workers-and-pages Bot commented Jul 26, 2026 •

edited

Loading