docs(devsecops): add Policy as Code section

[s1ns3nz0]

What does this PR change?

Adds a new policy-as-code section under DevSecOps, covering how a policy engine is applied
across the CI/CD pipeline and what NIST SP 800-204D requires of it.

Four pages under docs/pages/devsecops/policy-as-code/:

• Overview — what a policy engine decides, the two evaluation modes (pipeline artifacts vs.
  platform configuration), and the four places SP 800-204D names a policy enforcement engine
• Policy in the CI Pipeline — commit, merge, and build gates
• Policy in Release and Runtime — publishing identity, deployment gates, drift detection
• Governing the Policy Set — which violations block, who may override, where thresholds come
  from, and how rules are owned and retired

The existing DevSecOps pages document which controls to enable. These pages cover the decision
layer above them: what the engine evaluates, what evidence each stage produces, and which
decisions a person is allowed to override. Every control referenced here links out to the page
that documents it rather than restating it — continuous-integration-continuous-deployment,
repository-hardening, security-testing, code-signing, and the isolation/ pages.

Background

This follows a series I recently wrote on NIST SP 800-204D and CI/CD supply chain security:
https://miata.cloud/tags/cicd-security/

The standard's coverage here follows that series. The policy-decision material — rule
classification, threshold derivation, exception handling, and ownership — is new and specific to
this contribution.

On AI assistance

I am not a native English speaker, and I used AI assistance heavily for the English prose. The
structure, scope, and technical decisions are mine, and I verified every claim against its
source:

• NIST SP 800-204D section 5 and Appendix A, read directly rather than summarized. The page
  states that the standard names a policy enforcement engine and names OPA as an example, not
  that it mandates either — section 5.1.1 uses "techniques such as," and 5.1.2 uses "(e.g., Open
  Policy Agent (OPA))"
• CVE-2025-30066 (tj-actions/changed-files), against the NVD entry
• The Ledger Connect Kit timeline, against Ledger's own incident report
• All Rego examples validated against OPA 1.4.2, including the expiring-exception behaviour that
  the governance page's argument depends on

Flagging this because the contributing guidelines draw a line at content entirely generated by
AI. I do not believe this crosses it, but I would rather say so up front than have it surface in
review.

Notes for reviewers

Rego is fenced as python. The site's Shiki bundle has no Rego grammar, and an unrecognized
language fails the build. Python is the closest available approximation and highlights Rego
reasonably. There is a note to that effect at the bottom of the overview page. Happy to switch to
an unhighlighted fence if you would prefer accuracy over readability here.

Folder rather than a single page. The material ran past 1,500 lines. Following the structure
of devsecops/isolation/, it is split into four pages of 257–526 lines each, which is within the
range of existing DevSecOps pages.

Normalization standard. Rebased onto develop and applied the standard from #561 and the
sentence-case rule from #595: Further reading instead of Further Reading & Tools, and
What this framework covers for the overview's page map. pnpm run validate:content --path docs/pages/devsecops/policy-as-code reports 4 passed, 0 failed.

One validator issue worth flagging. utils/validate-content.cjs extracts headings without
stripping fenced code blocks, so a line-start # comment inside a code block parses as an H1.
Any ### that follows is then reported as heading_level_skip. This fired on two of these
pages because Rego uses # for comments. I worked around it by moving the comments into the
surrounding prose, but the same thing will hit any page with Python, Ruby, shell, or YAML
comments at line start. The fix is a one-line change: run stripCode(body) before headings().
Happy to open a separate PR for that if useful.

Verification

• pnpm run docs:build passes
• pnpm run validate:content --path docs/pages/devsecops/policy-as-code: 4 passed, 0 failed
• cspell clean (added Rekor to wordlist.txt)
• markdownlint-cli2 reports 0 issues across all four pages
• All internal links resolve to existing files
• Rego examples re-validated against OPA 1.4.2 after the comment changes

Type of change

• New content
• Edit to existing content
• Outline / structure change
• Typo or formatting fix
• Tooling / config

If applicable

• Editing existing content: tagged the current contributors from the attribution list
• Framework has a steward: asked them to review
• Outline change: updated vocs.config.ts with the dev: true parameter
• Want community feedback: shared this PR in our Discord

[github-actions]

Sidebar Configuration Reminder

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

• docs/pages/devsecops/policy-as-code/ci-pipeline.mdx (added)
• docs/pages/devsecops/policy-as-code/governance.mdx (added)
• docs/pages/devsecops/policy-as-code/index.mdx (added)
• docs/pages/devsecops/policy-as-code/overview.mdx (added)
• docs/pages/devsecops/policy-as-code/release-and-runtime.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.}

[frameworks-volunteer]

Model: z-ai/glm-5.2 Reasoning: medium Provider: openrouter

Security review: clean. No hardcoded secrets, no injection vectors, no unsafe code patterns. Rego snippets are illustrative and fenced as python (documented workaround for the Shiki grammar gap). All external links are legitimate.

QA review: well-structured, technically sound, and consistent with existing DevSecOps conventions. Internal links resolve, frontmatter is valid, wordlist additions are appropriate, sidebar has dev: true, and the index.mdx for the new folder matches the isolation/ pattern.

One minor nit:

• overview.mdx line ~203: "Two things have to come from your organization." is followed by three bullet points. Update the count to "Three" or merge the second and third bullets.

Approving — the nit above can be addressed in a follow-up commit.

[s1ns3nz0]

Thanks for the review. Fixed the count nit in 5ee026e — the third bullet was a restatement, so I folded it into the rule-content bullet and kept "Two things".

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
frameworks	✅ Ready (View Log)	Visit Preview	5ee026e

[scode2277]

I've left a few comments on the content with both one-click apply suggestions and requests for updates on your end.

Also, reviewing the overview page, I think that the basics paragraph is a little bit too verbose and could use a trim, as we don't want to overwhelm readers from the landing page of the subsection.

Feel free to tag me again here as soon as these things get implemented + merge conflicts get solved so I can provide a final review!🙏🏻

[s1ns3nz0]

Thanks for the thorough review @scode2277 — all six comments are addressed in b59aec2, and the merge conflicts are resolved.

Suggestions applied as written:

• overview.mdx — both SP 800-204D attribution fixes. You're right that "officially recommended" overstated it; the standard names the technique and gives OPA as an example, and that's what it says now.
• ci-pipeline.mdx — tj-actions passage rewritten with your figures and the NVD link.
• release-and-runtime.mdx — the publish-stage paragraph was indeed a restatement of the "two stages hold by convention" section further down. Replaced.

Python-fence note: removed from overview.mdx (that page has no code blocks, so the reference was dangling as you said) and added once above the first Rego block on each of the three pages that do have them.

RFC modality: applied. While doing it I found docs/pages/contribute/style-and-terminology.mdx says to use RFC modality in "procedures, checklists, and requirements", so I applied it to all four checklists rather than just governance.mdx — happy to narrow it back if that's more than you intended.

Overview trim: "The basics" went from ~70 lines to ~45. I folded the policy-data explanation into its own definition bullet, collapsed the SSDF and 800-204D sub-bullets into one line each, and dropped the bulleted restatement of the enforcement-point consequences. Kept the PDP/PEP table since it carries the "one engine, many enforcement points" idea that the rest of the section builds on — let me know if you'd rather that moved to a stage page too.

Conflicts: rebased onto develop. docs/pages/devsecops/overview.mdx had been rewritten into the numbered "What this framework covers" list by #587, so I took that version and inserted Policy as Code as item 14, renumbering the two below it.

Verified: validate:content 4 passed / 0 failed, markdownlint clean, cspell clean, docs:build passes.

Ready for another look whenever you have time.

[scode2277]

Thanks for all the work! I've reviewed everything again and I've noted a couple things still:

• The rego notes: I've actually looked better into the errors and it appears that the problem is to be Shiki's (vocs' provider of language support) + vocs' (our docs framework). I will take over this matter and will file issues on both their repos to solve this so we can actually use the correct code fences.
  For now, please remove the notes and leave the python blocks as they are. I'll switch them over once the issues are solved.
• I've noted there is a fair amount of you/yours across all the pages. We recently updated our style guide and content model to avoid this. We prefer to keep the content as broad as possible, without assuming it will only be read by individuals rather than by organizations or teams too. Could you update those references please?

Thanks for flagging the validator bug, I'll take it over from here, no need for a separate PR on your side.

Again, thanks for this work and let me know when these are sorted so I can approve this!🙏🏻

[s1ns3nz0]

Both done in 052648f.

Rego notes: removed all three. Thanks for digging into the actual cause — I'd assumed it was a fixed limitation. The python fences are untouched, ready to switch over once the Shiki/vocs issues land.

Second person: replaced all 24 occurrences of you/your across the four pages. I used the "concrete subjects: teams, operators, signers, maintainers, responders, stewards" line in the style guide as the reference — so you configure became to configure, your infrastructure became a specific infrastructure, whether you are affected became whether a release is affected, and so on. One heading changed as a result: "What a policy engine gives you" → "What a policy engine provides". Nothing links to the old anchor.

Understood on the validator, I'll leave that with you.

validate:content 4 passed / 0 failed, markdownlint and cspell clean, docs:build passes. Ready when you are.