mcp-ai-wpoos-ecosystem-port
Operational guide for the base+pro → Content Graph ecosystem port loop — porting Pro addon files byte-identical into plugins/nvoos-content-graph-pro cluster-by-cluster (transform rules, byte-identity
SKILL.md.agents/skills/mcp-ai-wpoos-ecosystem-port/SKILL.md
GitHubEcosystem Port Loop — Base+Pro → Content Graph Pro Addon
Operational playbook for the additive base+pro → Content Graph ecosystem
port (decision D5, Waves E/F). Each cluster ports base Pro addon files
byte-identical into the standalone plugins/nvoos-content-graph-pro addon,
wires standalone-only tool/module registration, validates both test matrices,
then self-merges after the two PHPUnit Pro Addon CI checks pass. Distilled
from the Wave F2 toolkit clusters (CRM through comic-creation, ending at
#6508) and the Wave F3 RF-DETR cluster (#6825, sub-cluster 1 complete).
Canonical references (read before starting a wave)
- Plan:
docs/project/plans/base-pro-ecosystem-port-plan.md(wave slicing, D8-compat rules, ownership boundaries). - State:
docs/project/ecosystem-port-tracker.md(per-cluster landed entries + the "Remaining:" tail — the source of truth for what's next). - Porting rules:
plugins/nvoos-content-graph-pro/README.md(§Porting rules) and the per-folder READMEs. - Test env:
.agents/skills/mcp-ai-wpoos-test-suite/SKILL.md("Pro addon dual-matrix runs" + cross-worktree one-off runner). - Monolith registration map:
addons/pro/mcp-ai-wpoos-pro.php→wp_mcp_ai_pro_register_tools()— the authoritative per-toolkit tool maps (gated onenable_*_toolkitsettings).
The loop (per cluster)
- Pick the next slice from the tracker's "Remaining:" tail (usually: data layer → tool batch(es) → admin slice → blueprint/extras).
- Fresh branch from
origin/alpha-working— only after the previous cluster's PR is MERGED (the next slice edits the same init/tests):git fetch origin alpha-working && git switch -c feat/ecosystem-port-<slug> origin/alpha-working. Nevergit checkout alpha-working(other worktrees own it). Stage explicit paths only — nevergit add -A, nevervendor/. - Port byte-identical with the documented transforms (below).
- Wire standalone-only registration (below) — tool filter, ecosystem registration, registry module, entry autoloader probe.
- Write characterization tests — derive every asserted constant from the
ported source first (see test-suite skill pattern 41:
mcp_ai_comic_char, notmcp_ai_comic_character). - Verify:
php -lthe new files; PHPCS (--standard=plugins/nvoos-content-graph-pro/phpcs.xml.dist; phpcbf for array alignment; exit 0 required); the byte-identity verifier (below); then local dual-matrix Docker runs (filter first, then full). - Update the tracker: append the sub-cluster entry before the row's "Remaining:" tail and rewrite the tail (remove landed slices).
- Commit → push → PR to
alpha-workingwith the standard body (what landed, documented deviations, standalone-only wiring, validation). - Merge after both
PHPUnit Pro Addon/testchecks pass (monolith + standalone). The PHP Linting workflow (WPCS 3.0 + PHP Compatibility) is repo-wide and takes 20–30 min — local PHPCS on the changed files is the substantive gate; watch withgh pr checks <n> --repo nvdigitalsolutions/mcp-ai-wpoos. - Start the next cluster from the merged
origin/alpha-working.
Port transforms (byte-identity rules)
Every ported file keeps the body byte-identical with exactly these documented deviations:
- Prepend a port-note header: source path, "Kept byte-identical", ownership
boundary ("the base Pro addon owns the class in monolith installs — the
addon boots nothing when
WP_MCP_AI_PRO_PATHis defined"), and the documented deviations list. - Add
declare(strict_types=1);after the header. - Text domain:
mcp-ai-wpoos-pro→nvoos-content-graph-pro(for base-owned D8-compat copies the source domain ismcp-ai-wpoos— swap tonvoos-content-graph-proeither way). WP_MCP_AI_PRO_PATH . 'includes/→NVOOS_CONTENT_GRAPH_PRO_PATH . 'src/(and_URL/_VERSIONswaps).- Source directories differ per ownership: Pro-owned files come from
addons/pro/includes/; base-owned D8-compat copies (tool interface, traits,WP_MCP_AI_Logger, image base, etc.) come fromincludes/. - Interface copies track the base file. When the base
includes/interfaces/interface-wp-mcp-ai-tool.phpgains a new optional interface (e.g.WP_MCP_AI_Tool_Data_Contract_Interface,WP_MCP_AI_Tool_Usage_Guidance_Interface), port it into the CG copysrc/interfaces/interface-wp-mcp-ai-tool.phpin the SAME relative position BEFORE any CG tool implements it — a CG class implementing an undefined interface is a compile-time fatal in standalone mode (the monorepo root classmap masks it in monolith runs). Precedent: #6740 portedUsage_Guidance(interface first, then the member-mirror classes) and synced the copy's stale Data_Contract docblock example with the base. - Allowed seams (only where the source requires base-owned files):
defined( 'WP_MCP_AI_PATH' )guards,file_exists-gated requires resolving to the addon'ssrc/copies,class_existsre-checks with the byte-identical degrade error. Never change behavior beyond the documented seam.
Byte-identity verifier
Write a one-shot bin/verify-<cluster>.php that RECONSTRUCTS the expected
ported body instead of reversing the destination (the port script has already
replaced the source's own docblock header with the port-note header, so the
raw source can never diff cleanly):
- Expected side: take the source file, strip its OWN docblock header (cut at the FIRST closing comment marker — the same cut the port script makes), then apply the same transforms the port script applies (path swap, text-domain swap).
- Actual side: take the destination, strip the port-note header (its first
closing comment marker closes the port header), strip the added
declare(strict_types=1);line. - Normalize both: collapse 3+ newline runs to
\n\n, ltrim leading newlines, thenrtrim-compare.
Traps: never write */ inside a verifier's own docblock/comment (it closes
the comment early — parse error); cutting the DESTINATION at the port
header's end must not cut the source's own docblock on the EXPECTED side (use
the source cut on the source, the port cut on the destination). Use
per-pair source path + source domain (Logger: includes/ + mcp-ai-wpoos;
CPTs/tools: addons/pro/includes/ + mcp-ai-wpoos-pro). Delete the verifier
after use — only bin/port-cluster.sh is committed; per-cluster verifiers are
scratch.
Standalone-only wiring pattern
The base tree ships many inits that NOTHING loads monolith; standalone needs new wiring (documented as a deviation every time):
- Slim init
src/tools/<toolkit>/init.php: full-body! defined( 'WP_MCP_AI_PATH' )runtime guard whenever the base init declares the same global helper functions (compile-time fatal otherwise); CPT requires; deferred admin/research-add/consolidate requires file-gated until those slices land; the byte-identical CPT init hook priority + enqueue helper. - Tool filter:
wp_mcp_ai_pro_register_<toolkit>_tools( $tools )onwp_mcp_ai_pro_tools— mirrors the monolith's inline map (subset/inert standalone), empty maps that fill as tool batches land. - Ecosystem registration:
wp_mcp_ai_pro_register_<toolkit>_ecosystem_tools()— register each tool into the graphToolRegistryviaWP_MCP_AI_Pro_Tool_Adapterand wrap into the nvoos/core registry via the AI addon'sGraphToolAdapter(duplicate slugs non-fatal). - Registry module: standalone-only
toolkit_<name>module inWP_MCP_AI_Pro_Module_Registry::define_modules()(files guard on the init; "the base tree ships the init but nothing loads it" comment). Updatetests/test-module-registry.php$expected— count the list yourself, do not trust handoff ordinals. - Entry autoloader: add the
src/tools/<toolkit>/(+examples/,harmonization/…) subtree probe innvoos-content-graph-pro.php. - Tree-only files (not in the monolith map — CC extras, import-blueprint tools) are standalone-only registrations (CRM CC-extras precedent).
Validation & test conventions
- Serving-source assertions: monolith asserts
includes/<file>; standalone acceptsnvoos-content-graph-pro/src/<file>ORincludes/<file>for base-owned D8 copies (the monorepo root classmap may serve base symbols in the test matrix — real standalone installs have no root vendor). - Capability variance is per-tool, not per-batch: before writing the
surfaces test,
grep get_required_capabilityacross the whole batch — law-firm batches shippedmanage_optionson 1–3 tools per batch (billing-trust ×3, document-drafter) while the rest carryedit_posts. Assert a capability map, not a uniform string. - Gate-test choice: pick a tool whose
execute()isedit_posts-gated AND has amissing_requiredfirst gate after the availability check — grepmissing_requiredacross the batch first. Some tools compute with defaults (no missing-required gate: damages-calculator), and amanage_options-gated tool returnswp_mcp_ai_forbiddenbefore any argument gate. Verify the gate ORDER (some tools require the calculator BEFORE the argument gate — that's fine; deterministic either way). - Hook assertions on init wiring are first-loader-gated where earlier suites require the init in-process.
- Admin-slice in-init wiring can't be asserted standalone: the standalone
test matrix boots with
is_admin()false, so an init'sis_admin()-gated admin block never fires there. Assert gate targets viaassertFileExistsand wire pages directly via their own::init()calls (PM/calendar precedent). Probe the actual state with a scratch test when unsure (is_admin(),function_exists( 'wp_mcp_ai_is_base_version' )). - Local matrix parity: standalone ~1 skip, monolith skips every standalone-gated test (hundreds — not failures).
- Per-matrix commands + Docker one-off runner: see the test-suite skill.
Common pitfalls
Resuming mid-cluster: verify the worktree against the handoff before trusting it (
git status+lsthe target dir) — a reset worktree keeps the branch but drops uncommitted ports. Re-porting from scratch is cheap (port scripts re-read the source); just redo port → verify → wire → test.Port scripts echo success on failed writes:
file_put_contentsinto a missing directory only warns and the script still prints "ported:". Create the destination subdir FIRST (mkdir), and always follow the script withphp -l+lson the new files.Constant drift: assert source constants, not guesses (comic character slug is
mcp_ai_comic_char).Module ordinals: count from the registry test list.
Double-declaration hazards: never copy a symbol the root classmap serves; use D8-compat copies only for
includes/tools/(classmap-excluded) symbols.Seam needles must be the FULL require expression (
require_once WP_MCP_AI_PATH . 'includes/...php';), never just the filename: a partial needle silently misses, the leftover path swap then leaves a BARE addon-pathrequire_once, and the root classmap's base copy- the addon copy double-declare mid-suite (site-creator/docgen precedent — surfaced as "Cannot declare trait X … already in use" in the standalone matrix).
No-autoload seams for non-self-contained D8 copies: when a base-owned copy itself references
WP_MCP_AI_PATH(e.g. self-hosted-ocr-client), a plainclass_exists()seam lets the monorepo root classmap win the autoload race and fatals on the undefined constant. Useif ( ! defined( 'WP_MCP_AI_PATH' ) && ! class_exists( 'X', false ) )(no autoload) — and replace only the FIRST occurrence (the seam): inner execute-timeclass_existsavailability checks stay byte-identical.Re-porting wipes post-steps: port scripts re-read the source, so phpcbf whitespace fixes, header notes, and domain patches are lost on every re-run — keep those post-steps scripted (php -r batch) and re-apply after each re-port.
phpcbfexit 1 = fixed files (not an error); re-run phpcs for exit 0. Do NOT chainphpcbf && phpcsand read the combined exit code — run phpcs alone to verify exit 0.Transient Docker slowness: a filtered matrix run can hang mid-suite and hit a 600 s timeout; retry with
timeout_ms900000 before investigating.Trackers are huge: edit only the row tail (append sub-cluster entry + rewrite "Remaining:"), never the historical entries.
Guidance-sweep drift (~957 files, tracked as #6741). The v1.1.83 Tool Description Engineering sweep added
get_usage_guidance()to the addon trees but was never ported to the CG mirrors — ~957 files undersrc/tools/whoseaddons/pro/includes/tools/counterpart carriesWP_MCP_AI_Tool_Usage_Guidance_Interface. Lint-invisible (the CG phpcs standard lacks theWPMCPAI.Tools.ToolDescriptionGuidancesniff; the root sniff is warning-severity), so CI stays green. When a guidance-port cluster is picked up, port the guidance block (text domain swapped per the transforms above) + add the interface to the class declaration; the member mirrors (PR #6740) are the precedent. Measurement:for f in $(find plugins/nvoos-content-graph-pro/src/tools -name "*.php" -not -name "init.php"); do grep -q "Usage_Guidance" "$f" && continue addon="addons/pro/includes/tools/${f#plugins/nvoos-content-graph-pro/src/tools/}" [ -f "$addon" ] && grep -q "Usage_Guidance" "$addon" && echo "$f" done