docs(governance): fix schema-invalid custom_policies/shared_exclusions examples#3202
Merged
Merged
Conversation
…s examples 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
1 participant
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.
Cherry-pick of the real schema-validity fix from #3143. Closes the example-vs-schema gap that PR identified, in a small focused PR.
What's wrong on main
Both
custom_policies[]andportfolio.shared_exclusions[]are defined insync-plans-request.jsonasPolicyEntry[]— each entry requirespolicy_id,enforcement, andpolicytext. The existing docs use plain strings:A reader copy-pasting these examples and validating against the schema fails. If the JSON blocks ever get a
$schemaref fortests/json-schema-validation.test.cjsto pick up, CI would flag them.What this PR changes
docs/governance/campaign/specification.mdxcustom_policiesandshared_exclusionsplain-string examples toPolicyEntryobjectsshared_exclusionsdescription from "Natural language exclusion rules" to "Bespoke exclusion policies applied to all member plans, using thePolicyEntryshape"<Warning>block in the Policy resolution section calling out the additive-only invariant frompolicy-entry.json— directly visible to anyone reading the spec on policy resolution rather than buried two pages awaydocs/governance/campaign/tasks/sync_plans.mdxcustom_policiesexamplecustom_policiesandportfolio.shared_exclusionsto reflectPolicyEntryshape with cross-link to policy resolutionWhy this PR (vs. just landing #3143)
#3143 was drafted by claude-triage for #3140 and bundled this schema fix with the broader sync/versioning content. PR #3187 (merged) covered the sync/versioning content via a new sibling page (
policy-registry-sync.mdx), leaving #3143's schema-fix portion still needed. This PR cherry-picks just that fix; #3143 will be closed.Test plan
npm run test:docs-nav— passesschemas/latest/references indocs/🤖 Generated with Claude Code