Skip to content

docs(governance): Policy Registry sync and versioning guidance#3143

Closed
bokelley wants to merge 2 commits into
mainfrom
claude/issue-3140-policy-registry-sync-versioning-docs
Closed

docs(governance): Policy Registry sync and versioning guidance#3143
bokelley wants to merge 2 commits into
mainfrom
claude/issue-3140-policy-registry-sync-versioning-docs

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

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.mdx

  • Expands "Temporal enforcement" with a worked effective_date example (informational info-severity findings before the date, blocking enforcement after) — consistent with the existing table's "reported at info severity" phrasing
  • Adds requires_human_review is not gated by effective_date — the human-review mandate fires as soon as a policy is resolved, not on the enforcement date
  • Adds sunset detection guidance: pull-based wall-clock evaluation per check_governance call; no push notification; inspect resolved_policies / policies_evaluated to confirm active set
  • Cross-links "Version tracking" bullet to specification#version-pinning

docs/governance/campaign/specification.mdx

  • Bug fix: custom_policies and shared_exclusions examples were plain strings; the schema (sync-plans-request.json) defines both as PolicyEntry[] requiring policy_id, enforcement, and policy text. Schema-invalid examples would fail CI JSON validation if they carried $schema refs.
  • Adds "Version pinning" subsection under "Policy registry" explaining the policy-ref version field, the protocol-silence caveat on when unversioned plan-level policy_ids re-resolve, and a stability note linking back to the existing "under development" caveat
  • Adds additive-only <Warning> block in "Policy resolution" section — quoted from the schema description in policy-entry.json

docs/governance/campaign/tasks/sync_plans.mdx

  • Same custom_policies plain-string bug fix in the request example
  • Updates custom_policies and portfolio.shared_exclusions field table descriptions to reference PolicyEntry shape and link to policy resolution

Non-breaking justification

Docs-only changes across three MDX files. No schema modifications. No URL changes. Changeset is --empty (no protocol impact). sync_plans surface is x-status: experimental.

Pre-PR review

  • code-reviewer: approved — 1 nit (anchor link #policy-registry#version-pinning, fixed before merge); schema-mismatch fix confirmed correct
  • ad-tech-protocol-expert: approved with 2 blockers fixed — (1) "must-level violations" language corrected to "blocking severity" to avoid conflating enforcement level with finding severity; (2) "de-resolved by a plan amendment" replaced with "no longer matched after a plan re-sync" to avoid naming a nonexistent protocol concept

Session: https://claude.ai/code/session_01XuqvXPFRgFRL9tWA9drHCM


Generated by Claude Code

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
@bokelley

Copy link
Copy Markdown
Contributor Author

Superseded by two PRs:

Closing as superseded — both pieces of the original scope are landing in the two PRs above.

@bokelley bokelley closed this Apr 25, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document Policy Registry sync pattern: version pinning, change handling, effective_date transitions

2 participants