chore: scripts - Clean up legacy portfolio tooling #452

Chore Summary

Clean up legacy portfolio-oriented tooling within scripts/ in lightspeedwp/ThisOneTimeOnAcidCom, keeping retained material relevant to thisonetimeonacid.com.

The review read all 46 files at revision 6b3b76baa955acdfaee0d5e4aef39e099b4b083e. It found no literal ashshaw.makeup references or standalone documentation files within this directory.

scripts/export-to-markdown.ts retains portfolio/about exports and obsolete journal metadata. Decide whether it remains necessary before approving its rewrite or retirement.

Linked Stories/Tasks/PRs

Attach the complete Markdown review report linked above as issue context.

#254 covers script-directory placement; it is context only. This cleanup does not authorise relocation or changes to that issue.

No implementing pull request or parent epic is established.

Milestones & Timeline

No milestone or deadline requested.

Scope / Affected Areas

Review and clean up scripts/ recursively:

• Agree the legacy exporter’s disposition; do not assume a rewrite or retirement.
• Assess conditional removal of scripts/lib/test-server-utils.js, scripts/validate-all.test.mjs, scripts/git-merge-utils.test.js and scripts/validation/check-locked-file-approval.cjs.
• Remove exporter helpers only if exporter retirement is approved.
• Preserve unique test coverage, active callers and current-site functionality.

Exclude unrelated findings, bulk content deletion, directory relocation and changes outside scripts/. Seek revised approval if dependencies require broader changes.

Steps / Checklist

• Task is clearly defined and actionable
• Does not fit the Code Refactor or Maintenance templates
• Documentation updated if affected
• PR uses correct branch prefix (chore/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards

Acceptance Criteria

• Task completed and verified in the affected areas
• No regressions introduced
• Exact retain/rewrite/delete dispositions and protected-file approval are recorded before implementation.
• Deletions leave no dangling callers and preserve relevant test coverage.
• Exporter changes follow an explicitly approved current-site requirement.
• Existing editorial sources are not deleted merely because the exporter is obsolete.
• Applicable verification results and remaining limitations are recorded.
• Unrelated findings remain outside this cleanup.

Additional Context

The attached report records static inspection, not executed tests or completed cleanup.

The entire scripts/ directory is protected and requires the repository’s human-approved change process.

Template references to chore/ conflict with the verified repository branch guidance below; they do not override it. Template checklists do not authorise linked-record changes, branch deletion, merging or deployment.

New-issue synchronisation is unverified; configured integrations may propagate the proposed title, description or labels externally.

Branch instructions

• Proposed branch: refactor/scripts-legacy-cleanup; not created.
• Base and PR target: current origin/develop / develop.
• Repository code-change classification differs from the Linear housekeeping classification.
• Use the shared pr_refactor.md template; its contents must be retrieved before preparing a PR.
• Preserve protected-file approval requirements. Do not modify centrally managed workflows.
• Repository evidence: CONTRIBUTING.md, docs/BRANCH_NAMING_LOCAL.md, scripts/validate-branch-name.js and .github/PROTECTED_FILES.txt.

Definition of Ready (DoR)

• Task/goal described and scoped
• Confirms it does not fit the Code Refactor or Maintenance templates
• Acceptance criteria listed
• Estimate added (if applicable)

Definition of Done (DoD)

• Affected files, labels, or settings updated and documented
• PR uses correct branch prefix (chore/)
• Branch deleted after merge
• Approved by at least one maintainer
• Issue is verified as completed
• Documentation/changelog updated if needed
• Linked issue(s) updated with latest status and closed after merge,
• The related epic should not be closed, instead updated with a comment to reflect the closed issue

File-by-file cleanup plan — 24 October 2026

I recommend retiring the legacy exporter conditionally, rather than rewriting it before the book website’s content-source and publication requirements are agreed.

This is a read-only draft for #452. I read the complete attached report and checked current develop at 3f583002482d80ffd1910676bcf7c63e13989b20: all 46 files under scripts/ remain unchanged from the reviewed revision.

1. Exporter retirement decision

The exporter retains portfolio/about behaviour, writes obsolete metadata and can overwrite content. No current package command or tracked external caller was found—but that does not rule out manual use.

Do not run the exporter or delete its source content as part of cleanup. If an ongoing export requirement is confirmed, retain all three files and prepare a separately approved rewrite specification.

2. Redundant utilities and test consolidation

The standalone validation suite launches fetch/report-writing paths. It should not be executed merely to establish whether it can be deleted.

3. Exact test-file edits proposed

These are the only edits proposed among the other 39 retained files:

Blocker: a genuinely non-writing cleanup-branches.js --help path needs a production-code repair. That file is otherwise retained unchanged; repairing it requires a revised change-set proposal. Do not discard the intended safety contract merely to remove the old suite.

4. Retain unchanged

Beyond the six test files above, retain these 33 files:

• Root: check-journal-links.ts, check-netlify-headers.mjs, cleanup-branches.js, extract-figma-assets.js, journal-schema.ts, netlify-hashed-asset-headers.mjs, parse-journal-markdown.ts, pr-template-router.js, run-validator-tests.js, test-figma-access.js, test-push-validator.sh, test-server.js, test-server.test.js, update-catalogue-recovery.js, validate-branch-name.js, validate-extracted-assets.js, validate-push-branch.js, verify-netlify-redirects.ts
• lib/: branch-categorization.js, constants.js, git-merge-utils.js, test-server-handler.js
• validation/: compare-jest-failures.cjs, compare-jest-failures.test.js, validate-changelog.cjs, validate-labeling-configs.cjs, validate-labels-before-creation.cjs
• Other directories: __tests__/test-figma-access.test.js, agents/__tests__/label-contracts.test.js, agents/includes/changelogUtils.cjs, agents/run-labeling-agent.js, claude/setup.sh, claude/validate.sh

Retain does not mean defect-free. Unrelated report findings remain outside this cleanup.

Implementation sequence and boundaries

1. Obtain protected-file approval and confirm exporter consumers, guard authority and the exact deletion list.
2. Add and verify replacement test coverage before removing duplicate suites or utilities.
3. Delete only cleared files, run approved isolated checks, and record commands, results, remaining blockers and a content-preservation diff.

All scripts/ files are protected. No directory relocation, content deletion, managed-workflow changes or blanket remediation of the report’s 17 findings is included. Changes outside scripts/—including contributor documentation or changelog updates—need a separate exact proposal.

No repository scripts, tests or builds were executed for this plan. No records or repository files were changed.