Continue USPS Label Broker filesystem-storage migration

next steps

• Update deploy plan with clarified branch flow and cron investigation.

key decisions

• Staging is a smoke-test vehicle; never merge staging into master.
• Production deployed from fast-forwarding master to usps-label-broker-fs-storage.

open questions

• LabelFormat=null response shape is unknown (existing code tolerates missing broker id).
• WP-cron mechanism on staging/production is unresolved.

next steps

• Implement response sampler for pre-activation response shape review.

key decisions

• WP-cron investigation is a gate for activation (Phase 3); loopback cron on staging confirmed later.
• Concurrent double-mint lock (review #10) is accepted as low-frequency risk, not fixed.

open questions

• Whether a supervisor/crontab runner exists on staging (noted for Phase 1).
• LabelFormat=null response shape still unknown.

next steps

• Update HANDOFF.md and deploy plan with sampler documentation.
• Staging deploy then first new-order mint will trigger capture.

key decisions

• Sampler captures before XML parsing to catch malformed responses.
• Sampler fires even in OFF/legacy mode, costs no extra USPS call.
• Sampler redacts base64 images to avoid storing PII in options.

open questions

• Actual USPS response shapes remain unknown until first live capture on staging.

next steps

• Push staging branch and deploy.
• After deploy, review sampled responses before flipping toggle ON.

key decisions

• USPSReturnsLabel API doc does not apply to this plugin's API; sampler is ground truth.
• Sampler results become the gate for activation on staging and production.

open questions

—

next steps

• Deploy staging site via Forge.
• Run Phase 2 rollout test: confirm OFF state, trigger sample capture, review response shape.
• After review, proceed to flip toggle ON and run migrate.

key decisions

• No new .env vars needed; only confirm existing Sentry DSN and WORDPRESS_CRON.
• Staging cron mechanism is loopback (confirmed via .env); note that quiet sites may lag.

open questions

• Whether a supervisor/crontab runner also exists on staging (not yet checked).
• Actual USPS response shapes unknown until first staging order mints.

next steps

• User to grant mferrara admin or org owner role on The-Darkroom org
• Approve Laravel Forge OAuth app access on the org
• Re-authorize GitHub connection in Forge
• Update repo remote and deploy to staging

key decisions

• Use GitHub admin role for mferrara as sole technical operator
• Do not merge staging into master during USPS rollout to avoid pulling additional changes

open questions

—

next steps

—

key decisions

• Use <td> with desktop CSS rule instead of fighting Woo's !important mobile rules to restore <th>
• Bump the theme's global style_loader_src cache-bust constant (functions.php:74) rather than enqueue version, since the filter overrides enqueue params

open questions

—

next steps

• Run Phase 2 checks: admin page, existing order render, new order render, response sample capture

key decisions

• Daniel's staging-only work is production-approved, so staging->master convergence is a legitimate follow-up after USPS rollout
• Deploy plan updated to reflect new branch state and that staging branch is pushed

open questions

—

next steps

• Run full migration dry-run on staging
• Flip toggle to ON for canary orders
• Run full migrate, then purge dry-run and force purge cron
• Verify post-migrate rendering from filesystem

key decisions

• Activation gate passed: response shapes match code expectations, no changes needed
• Nginx deny rule placed at server level with ^~ prefix to beat all regex locations
• All 6 staging canary orders are valid (within retention, have broker IDs)

open questions

—

next steps

—

key decisions

• Nginx deny rule added immediately after canary on staging (not post-activation) because files exist from that moment.
• Past-retention print-your-own fallback not testable on staging (no old orders); verify on production.

open questions

—

next steps

• Diagnose leaking nginx listener (sudo nginx -T, grep for tdr-usps-labels).
• Add Cloudflare WAF custom rule (URI starts with /shop/wp-content/tdr-usps-labels/ → Block).
• Purge Cloudflare cache for the prefix.
• Verify 403 from outside.
• Run full dry-run, flip ON, full migrate.

key decisions

• Full migrate gated on lockdown fix to avoid exposing tens of thousands of PII-bearing PNGs.
• Cloudflare WAF rule recommended as immediate fix before solving nginx puzzle.

open questions

• Which nginx server block (likely 443) is serving the label directory?
• Did nginx reload silently fail?

next steps

• Complete full dry-run in tmux to see full distribution.
• Fix nginx/Cloudflare lockdown.
• Flip toggle ON and run full migrate.

key decisions

—

open questions

—

next steps

• Flip the filesystem storage toggle ON via the admin page.
• Run the real migrate command in tmux.
• Lock down the nginx directory after migration completes.

key decisions

• Skip the full dry-run and go straight to production migration because correctness is already proven end-to-end.
• Proceed origin-unprotected (user explicit decision) — lockdown deferred until after migration completes.

open questions

—

next steps

• Lock down the label directory at nginx immediately — the migration completed and 57,866 PII files are web-accessible.
• Flip toggle ON to stop new orders from minting blobs.
• Run a second migrate pass to sweep the ~6200 new blobs.

key decisions

• Flower MCP is available for semantic recall; use it to check for out-of-band activity.
• SSH alias 'shop' works for read-only queries to production.
• The remaining ~6200 blobs are new orders from the week (toggle still OFF), not an unprocessed tail.

open questions

—

next steps

• Run: sudo tee /etc/nginx/forge-conf/thedarkroom/server/tdr-usps-labels-deny.conf with a 'return 403' location block.
• Reload nginx, verify 403 from origin.
• Document the sites-enabled vs sites-available divergence for a larger cleanup.

key decisions

• The deny block must go in forge-conf/thedarkroom/server/ for Forge durability, not directly in sites-available.
• The nginx sites-enabled file is a stale 2022 copy (not a symlink to sites-available) — all edits since 2022 have been dormant. This root cause explains why last time's fix didn't take effect.

open questions

—

next steps

• Promote the brief from 'idea' and add a resolution spec when the fix is planned.
• Run the symlink-fix procedure carefully (diff review, CF redirect verification, then ln -sfn).

key decisions

• Create the brief as a draft (is_draft: true) for the operator to review and promote.
• File under project tdr-thedarkroom so it appears in recall_open_loops.

open questions

—

next steps

• Flip toggle ON (admin page).
• Sweep ~3100 straggler blobs.
• Phase-4 verification.

key decisions

• The forge-conf server include directory is the correct inject point (survives Forge deploys).

open questions

—

next steps

• Flip toggle ON to break the purge-remint loop.
• Then do Phase-4 verification.

key decisions

• The purge-remint cycle is caused by legacy-mode early return in the read path while toggle is OFF. Flipping toggle ON is the fix.

open questions

—

next steps

• Zero out the 7 skipped no-broker orders by minting QR labels, then migrate again.
• Investigate HPOS readiness using WooCommerce's compatibility API.

key decisions

• Use a no-broker order for the mint-and-store test (fills a gap and completes the order).

open questions

—

next steps

• Write findings into HPOS_TRANSITION_NOTES.md.
• Spawn a Solo agent to investigate legacy REST API usage and build a scratchpad for rework planning.

key decisions

• Mint QR labels for the 6 no-broker orders to unstick their full-label blobs, then migrate to cleanly zero out.
• Use WooCommerce's standard compatibility API (FeaturesUtil) for the HPOS readiness check.
• 1 incompatible plugin (woocommerce-legacy-rest-api) and 10 uncertain plugins identified.

open questions

• What depends on the legacy REST API? Likely ShipStation and other integrations.
• Should the 10 uncertain plugins be declared compatible or investigated for actual issues?
• Is full rewrite of the legacy REST API usage needed, or just a config change?

next steps

• Read existing HPOS_TRANSITION_NOTES.md to append correctly.
• Read Solo playbook to follow the correct orchestration workflow.
• Write findings to HPOS_TRANSITION_NOTES.md.
• Spawn a Solo codex agent to investigate legacy REST API usage and build a scratchpad.

key decisions

• Append to existing HPOS_TRANSITION_NOTES.md rather than create a new file.
• Follow the Solo playbook for the sub-agent spawn.

open questions

—

next steps

—

key decisions

• Append the production landing notes to the existing HPOS_TRANSITION_NOTES.md file rather than creating a separate document.

open questions

—

next steps

—

key decisions

• Use Solo MCP delegation pattern (todo + spec scratchpad + Codex worker + idle-watch timer) for the audit.
• Write the spec to a file (.solo-spec-legacy-rest-api.md) so Codex can read it even without Solo MCP access.
• Constrain Codex to static analysis only (no wp/php/prod/code-changes) to avoid side effects.

open questions

—

next steps

• The refactor itself (replacing WooCommerceAPIWrapper with a /wp-json/wc/v3 adapter) is a separate effort not started here.

key decisions

• Spot-check Codex's claims against real files before trusting them — verification confirmed the load-bearing findings.
• Close the Codex process and remove the transient spec file to keep the workspace clean.
• The audit is complete; the refactor is deferred to a separate effort.

open questions

—