The canonical policy authoring guide (content/docs/insights/policy/policy-packs/authoring.md) never documents remediate, a first-class enforcement level shipped in pulumi-policy v1.8.0 (2023-10-10) and stable for roughly two and a half years.\n\nThree concrete gaps in that one page:\n\n1. The TypeScript and Python code-comment explanations of enforcement levels (around lines 93 and 186) each list only advisory, mandatory, and disabled, omitting remediate entirely.\n2. The page's own "Enforcement levels" reference section (under "Configuring policy packs") lists exactly three bullets -- advisory, mandatory, disabled -- with no remediate bullet and no <a id="remediate"> anchor, even though the section otherwise anchors each level.\n3. There is no authoring guidance anywhere on the page for how to write a remediation: no remediateResourceOfType (TypeScript) or remediate= (Python) example, and no mention of remediation-specific behavior such as stack policies being unable to remediate, or a violation that persists after remediation being downgraded to mandatory.\n\nThis is a real self-contradiction, not just an omission: sibling pages already document remediate correctly, so a reader following links from those pages into the authoring guide hits a wall. See content/docs/insights/policy/policy-packs/_index.md ("A policy can warn (advisory), block the deployment (mandatory), fix the violation automatically (remediate), or be turned off (disabled)") and content/docs/insights/policy/policy-packs/metadata.md (the enforcementLevel table row lists all four levels). The content/docs/insights/policy/api-reference.md page has the same silence on remediation as authoring.md.\n\nThis is also a differentiated Pulumi Cloud / policy-as-code capability (automatic compliance, not just warn/block), so leaving it undocumented in the one place a policy author would look to learn how to write one is a missed opportunity as well as a factual gap.\n\nProposed fix: correct the two code comments, add the missing remediate bullet/anchor to the enforcement levels list, and add a bounded remediation-authoring section with TypeScript and Python examples plus the verified behavioral notes above.
The canonical policy authoring guide (
content/docs/insights/policy/policy-packs/authoring.md) never documentsremediate, a first-class enforcement level shipped inpulumi-policyv1.8.0 (2023-10-10) and stable for roughly two and a half years.\n\nThree concrete gaps in that one page:\n\n1. The TypeScript and Python code-comment explanations of enforcement levels (around lines 93 and 186) each list onlyadvisory,mandatory, anddisabled, omittingremediateentirely.\n2. The page's own "Enforcement levels" reference section (under "Configuring policy packs") lists exactly three bullets -- advisory, mandatory, disabled -- with noremediatebullet and no<a id="remediate">anchor, even though the section otherwise anchors each level.\n3. There is no authoring guidance anywhere on the page for how to write a remediation: noremediateResourceOfType(TypeScript) orremediate=(Python) example, and no mention of remediation-specific behavior such as stack policies being unable to remediate, or a violation that persists after remediation being downgraded tomandatory.\n\nThis is a real self-contradiction, not just an omission: sibling pages already documentremediatecorrectly, so a reader following links from those pages into the authoring guide hits a wall. Seecontent/docs/insights/policy/policy-packs/_index.md("A policy can warn (advisory), block the deployment (mandatory), fix the violation automatically (remediate), or be turned off (disabled)") andcontent/docs/insights/policy/policy-packs/metadata.md(theenforcementLeveltable row lists all four levels). Thecontent/docs/insights/policy/api-reference.mdpage has the same silence on remediation asauthoring.md.\n\nThis is also a differentiated Pulumi Cloud / policy-as-code capability (automatic compliance, not just warn/block), so leaving it undocumented in the one place a policy author would look to learn how to write one is a missed opportunity as well as a factual gap.\n\nProposed fix: correct the two code comments, add the missingremediatebullet/anchor to the enforcement levels list, and add a bounded remediation-authoring section with TypeScript and Python examples plus the verified behavioral notes above.