Fix: Read Guidelines from wp_knowledge storage

[gziolo]

What?

Follow-up to #949. This extracts the Guidelines service repair requested in #949 (comment) so it can be reviewed and merged independently.

The service now reads published guideline rows from the shared wp_knowledge post type instead of the removed wp_guideline post type and its post meta.

Why?

Current Gutenberg stores each guideline scope and per-block guideline as its own wp_knowledge row. The AI plugin still queried the removed storage model, so prompt-building integrations quietly stopped receiving guidelines.

How?

• Read scope rows by their canonical guideline-{scope} slugs.
• Read block rows by their canonical guideline-block-{namespace}_{name} slugs.
• Use the shared scope and maximum-length APIs when available, with standalone fallbacks.
• Cache scope and block lookups independently.
• Ignore non-published rows so private knowledge cannot enter prompts.
• Update the shared integration fixtures and all dependent tests for the current storage model.

Use of AI Tools

AI assistance: Yes
Tool(s): OpenAI Codex
Model(s): GPT-5
Used for: Extracting the fix from #949, adapting it to remain standalone, identifying a registry key type-safety issue, and adding verification. The resulting diff and test output were reviewed.

Testing Instructions

The original Guidelines integration was implemented in #359 for #322. These steps adapt its testing instructions to the current wp_knowledge storage.

Automated testing

1. Start the test environment:

npm run wp-env:test start

2. Run PHP coding standards and static analysis:

composer lint
composer phpstan

3. Run the Guidelines-dependent integration tests:

npx wp-env --config=.wp-env.test.json run cli --env-cwd=wp-content/plugins/ai vendor/bin/phpunit -c phpunit.xml.dist --filter '/(Guidelines_Test|Abstract_Ability_Guidelines_Test|HelpersTest|Editorial_NotesTest)/'

4. Run the full regression suites:

npm run test:php
npm run test:e2e

5. Stop the test environment:

npm run wp-env:test stop

Validation on the latest commit:

• Targeted Guidelines-dependent suite: 154 tests, 401 assertions, and 4 existing skips.
• Full PHP suite: 1,453 tests, 4,093 assertions, and 44 existing skips.
• PHP coding standards and static analysis pass.

Manual testing without Guidelines storage

1. With no plugin providing the wp_knowledge post type, open a post and run a guideline-aware AI ability such as title generation.
2. Verify the ability completes normally without PHP errors or warnings. This confirms graceful degradation when Guidelines storage is unavailable.

Manual testing with the Gutenberg Guidelines experiment

1. Install and activate a Gutenberg build that provides the wp_knowledge storage, then enable Guidelines under Gutenberg → Experiments.
2. Open Settings → Guidelines and save distinctive Site and Copy guidelines. Optionally add a guideline for the Paragraph block.
3. Run title generation and verify the generated result reflects the Site and Copy guidance. Inspect the AI request through debug logging or the configured provider trace and confirm the system instruction contains <guidelines>, <site-context>, and <copy-guidelines>.
4. For the Paragraph block guideline, run a block-aware ability such as Type Ahead or Editorial Notes and confirm the system instruction also contains <block-guidelines>.
5. Clear a guideline, repeat the request, and verify the removed text is no longer injected.

[github-actions]

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

---

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

[codecov]

Codecov Report

❌ Patch coverage is 94.66667% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.62%. Comparing base (0833eec) to head (d26ca81).

Files with missing lines	Patch %	Lines
includes/Services/Guidelines.php	94.66%	4 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #988      +/-   ##
=============================================
+ Coverage      74.57%   74.62%   +0.04%     
- Complexity      3132     3151      +19     
=============================================
  Files            132      132              
  Lines          12213    12243      +30     
=============================================
+ Hits            9108     9136      +28     
- Misses          3105     3107       +2     

Flag	Coverage Δ
unit	74.62% <94.66%> (+0.04%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.

[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: gziolo <gziolo@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>

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

[dkotter]

Overall this looks good to me but any thoughts on a migration routine for those that had been using this? Not sure if we care about migrating existing Guidelines to the new post type and taxonomy or if we are fine with breaking changes here

[gziolo]

Good point. I worked on the upstream Gutenberg changes and can confirm we intentionally decided against migration. Guidelines is still an opt-in experiment, so we accepted the breaking storage change while the feature remains experimental.