docs(governance): Policy Registry sync and versioning guidance#3143
Closed
bokelley wants to merge 2 commits into
Closed
docs(governance): Policy Registry sync and versioning guidance#3143bokelley wants to merge 2 commits into
bokelley wants to merge 2 commits into
Conversation
Adds sync/versioning documentation requested by the governance working group, distributed across the files where each topic naturally belongs. Changes to policy-registry.mdx: - Expand "Temporal enforcement" with a worked effective_date transition example (informational findings before date, blocking enforcement after) - Add explicit section on requires_human_review independence from effective_date — human review fires unconditionally on policy resolution - Add sunset detection guidance (pull-based wall-clock evaluation; inspect resolved_policies / policies_evaluated; no push notification) - Cross-link "Version tracking" bullet to specification#version-pinning Changes to campaign/specification.mdx: - Fix custom_policies and shared_exclusions examples: both were plain strings but the schema requires PolicyEntry objects (policy_id, enforcement, policy text). Schema-invalid examples would fail CI JSON validation if they carried $schema references. - Add Version pinning section under "Policy registry" explaining policy-ref.json version field vs. unversioned plan-level policy_ids, with protocol-silence caveat on mid-campaign re-resolution semantics - Add additive-only Warning block in "Policy resolution" section Changes to sync_plans.mdx: - Fix custom_policies request example (same plain-string bug) - Update field table descriptions for custom_policies and portfolio.shared_exclusions to reference PolicyEntry shape Non-breaking: docs-only. No schema changes. Changeset: --empty. https://claude.ai/code/session_01XuqvXPFRgFRL9tWA9drHCM
…example Replace "blocking severity" (not in the escalation-severity enum) with "enforced at its declared level" to match the language already used in the Temporal enforcement table and the schema. https://claude.ai/code/session_01XuqvXPFRgFRL9tWA9drHCM
4 tasks
Contributor
Author
|
Superseded by two PRs:
Closing as superseded — both pieces of the original scope are landing in the two PRs above. |
bokelley
added a commit
that referenced
this pull request
Apr 25, 2026
…s examples (#3202) The sync-plans-request.json schema defines both custom_policies[] and portfolio.shared_exclusions[] as PolicyEntry[] (requiring policy_id, enforcement, policy text). The existing examples in specification.mdx and sync_plans.mdx used plain strings — a reader copy-pasting and validating against the schema would fail. Changes: - specification.mdx: convert two plain-string examples (custom_policies, shared_exclusions) to PolicyEntry objects; update shared_exclusions description; add additive-only Warning block in the Policy resolution section calling out the invariant from policy-entry.json. - sync_plans.mdx: convert custom_policies example; update field-table descriptions for both custom_policies and portfolio.shared_exclusions to reflect the PolicyEntry shape. Cherry-picked from PR #3143 (which is superseded by the merged #3187 for the conceptual sync/versioning content, but carried this real schema-validity fix). #3143 will be closed. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
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.
Closes #3140
Adds the sync/versioning documentation requested by the governance working group, distributed across the files where each topic naturally belongs rather than as a single new section in
policy-registry.mdx(per expert review — the five topics split cleanly across audience lines).What changed
docs/governance/policy-registry.mdxeffective_dateexample (informationalinfo-severity findings before the date, blocking enforcement after) — consistent with the existing table's "reported atinfoseverity" phrasingrequires_human_reviewis not gated byeffective_date— the human-review mandate fires as soon as a policy is resolved, not on the enforcement datecheck_governancecall; no push notification; inspectresolved_policies/policies_evaluatedto confirm active setspecification#version-pinningdocs/governance/campaign/specification.mdxcustom_policiesandshared_exclusionsexamples were plain strings; the schema (sync-plans-request.json) defines both asPolicyEntry[]requiringpolicy_id,enforcement, andpolicytext. Schema-invalid examples would fail CI JSON validation if they carried$schemarefs.policy-refversionfield, the protocol-silence caveat on when unversioned plan-levelpolicy_idsre-resolve, and a stability note linking back to the existing "under development" caveat<Warning>block in "Policy resolution" section — quoted from the schema description inpolicy-entry.jsondocs/governance/campaign/tasks/sync_plans.mdxcustom_policiesplain-string bug fix in the request examplecustom_policiesandportfolio.shared_exclusionsfield table descriptions to referencePolicyEntryshape and link to policy resolutionNon-breaking justification
Docs-only changes across three MDX files. No schema modifications. No URL changes. Changeset is
--empty(no protocol impact).sync_planssurface isx-status: experimental.Pre-PR review
#policy-registry→#version-pinning, fixed before merge); schema-mismatch fix confirmed correctSession: https://claude.ai/code/session_01XuqvXPFRgFRL9tWA9drHCM
Generated by Claude Code