Feature/content guidelines

[saarnilauri]

What?

Closes #322

Adds Content Guidelines integration to the AI plugin, allowing all AI abilities to respect site-wide editorial standards defined via Gutenberg's wp_content_guideline custom post type (introduced in Gutenberg 22.7+).

Why?

When sites define content guidelines (tone, style, image standards, etc.), AI-generated content should follow them. Without this integration, AI abilities operate without awareness of the site's editorial standards, producing output that may not align with the site's voice and style.

How?

New Content_Guidelines service (includes/Services/Content_Guidelines.php):

• Singleton that fetches and caches guidelines from the wp_content_guideline CPT
• Supports four categories: site, copy, images, additional, plus per-block guidelines
• Formats guidelines as XML-tagged strings (<content-guidelines>) for prompt injection
• Truncates per-category content to 2000 chars (filterable via wpai_max_guideline_length)
• Can be disabled via the wpai_use_content_guidelines filter
• Gracefully returns empty/null when the CPT isn't registered

Abstract ability opt-in pattern (includes/Abstracts/Abstract_Ability.php):

• New guideline_categories() method — subclasses override to declare which categories they use
• New get_content_guidelines_for_prompt() helper fetches and formats guidelines for the declared categories
• get_system_instruction() auto-appends a guidelines-awareness paragraph when categories are declared

Per-ability wiring — each ability declares relevant categories and injects guidelines into its prompt:

Ability	Categories
Title Generation	site, copy
Excerpt Generation	site, copy
Summarization	site, copy
Alt Text Generation	site, images
Image Generation	site, images
Image Prompt Generation	site, images
Review Notes	site, copy, additional

Review Notes also gains a new guidelines review type that flags content violating the editorial standards.

Helper functions in includes/helpers.php:

• get_content_guidelines() — retrieve guidelines (optionally filtered by category)
• format_content_guidelines_for_prompt() — format guidelines for prompt injection

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code (Opus 4.6 and Sonnet 4.6)
Used for: Initial planning and code implementation; finalization of implementation and tests were reviewed and edited by me.

Testing Instructions

1. Start the local environment: npm run test:e2e:env:start
2. Run the full test suite:
   • npm run test:php — runs unit/integration tests including Content_Guidelines_Test and Abstract_Ability_Guidelines_Test
   • npm run test:e2e — runs e2e tests including content-guidelines.spec.js
3. Manual testing (without Gutenberg 22.7+): Open any post, use title generation, excerpt generation, or any other AI ability — verify they work normally without errors (graceful degradation when the wp_content_guideline CPT doesn't exist).
4. Manual testing (with Gutenberg 22.7+): If the Content Guidelines feature is available, create a content guideline post with site/copy/images categories, then verify AI-generated content reflects those guidelines in the prompt (inspect via debug logging or network requests).

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: saarnilauri <laurisaarni@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

❌ Patch coverage is 93.18182% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.70%. Comparing base (8a0bebb) to head (ffd0b9b).

Files with missing lines	Patch %	Lines
includes/Abilities/Image/Generate_Image.php	57.14%	3 Missing ⚠️
includes/Abilities/Review_Notes/Review_Notes.php	40.00%	3 Missing ⚠️
includes/Services/Guidelines.php	96.59%	3 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #359      +/-   ##
=============================================
+ Coverage      65.75%   66.70%   +0.95%     
- Complexity       763      813      +50     
=============================================
  Files             53       54       +1     
  Lines           3863     3992     +129     
=============================================
+ Hits            2540     2663     +123     
- Misses          1323     1329       +6     

Flag	Coverage Δ
unit	66.70% <93.18%> (+0.95%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gziolo]

Based on the post from @aagam-shah: Guidelines Lands in Gutenberg 22.7. The final name is going to be Guidelines, and the plan is to drop the "content" prefix from the naming – confirmed here. It would be good to align with that direction in this PR and use the final name wherever possible.

Overall, this PR looks very solid and nicely tackles integration of general-purpose guidelines into existing functionality 👏🏻

[saarnilauri]

I will update the naming

[dkotter]

I agree, I think we can bump this up. 5000 characters sounds like a good place to start with

[saarnilauri]

Based on the post from @aagam-shah: Guidelines Lands in Gutenberg 22.7. The final name is going to be Guidelines, and the plan is to drop the "content" prefix from the naming – confirmed here. It would be good to align with that direction in this PR and use the final name wherever possible.

Overall, this PR looks very solid and nicely tackles integration of general-purpose guidelines into existing functionality 👏🏻

The naming is now updated.

[jeffpaul]

@saarnilauri once we get the 0.7.0 release out, will likely need to resolve merge conflicts here to get this ready for merge in the 0.8.0 release cycle

[dkotter]

Overall code looks good here but a few things of note:

1. Currently doesn't work for me. Doing some quick debugging, it appears the Content Guidelines post type stores in a draft state so our query doesn't work. Not sure if there's something I need to do to get those published or if this is expected
2. We've added a few new Abilities since this was opened and we should look to add guidelines support to those: Content Classification and Meta Descriptions

[saarnilauri]

I will look into the new abilities and add the guideline injections.

[gziolo]

Heads up, the process of renaming CPT to wp_guideline is in progress:

• Guidelines CPT: Changes slug from wp_content_guidelines to wp_guidelines gutenberg#77147

I also noticed that @iamchughmayank started some work around taxonomies:

• Registers wp_guideline_type taxonomy gutenberg#77156

While the current code works, we need to watch the Gutenberg release process and adjust support as needed.