Docs cleanup: remove orphaned summaries, fix changelog org links, and align API spec docs

[bytescape30]

Summary

Docs cleanup: remove orphaned summaries, fix changelog org links, and align API spec docs

What was solved

#1557 — Consolidate or archive orphaned root-level IMPLEMENTATION_SUMMARY*/PR_*/WORKFLOW_HARDENING docs

Clean up orphaned root-level one-off implementation/PR summary docs by consolidating durable content into permanent docs and removing stale PR-description artifacts, then documenting in CONTRIBUTING.md where durable implementation notes belong going forward.

Addressed:

• Changed: IMPLEMENTATION_SUMMARY.md
• Review each of IMPLEMENTATION_SUMMARY.md, IMPLEMENTATION_SUMMARY_CI_SECURITY_RELIABILITY.md, IMPLEMENTATION_SUMMARY_ISSUES_723_726.md, PR_DESCRIPTION.md, PR_QUERY_PAGINATION.md, and WORKFLOW_HARDENING.md.
• Merge still-relevant content into permanent docs (e.g. docs/architecture.md, CHANGELOG.md, runbooks) or docs/adr/-style history; remove content that is purely a stale PR description.
• Ensure the repository root no longer contains one-off implementation-summary files after cleanup.

#1558 — CHANGELOG.md compare/commit/issue links point to defunct GitHub org popsman01 instead of solutions-plug

Fix the defunct GitHub org links in the auto-generated CHANGELOG.md by updating the git-cliff configuration (cliff.toml) to reference the solutions-plug/predictIQ remote, bulk-correcting existing popsman01 links in CHANGELOG.md, and documenting the expected org so future drift is caught.

Addressed:

• Changed: cliff.toml, .github/workflows/protect-changelog.yml
• Update cliff.toml (or the git-cliff remote/repo configuration it reads) so future generated entries use the solutions-plug/predictIQ remote instead of popsman01/predictIQ.
• Correct existing popsman01 links in CHANGELOG.md (compare/commit/issue links) to solutions-plug, either by regeneration or bulk find/replace.
• Add a CI check or a cliff.toml comment documenting the expected org so the link target does not silently drift again after a future repo transfer.

#1559 — API_SPEC.md Pagination section is appended after the auto-generation marker and will be silently dropped on regen

Fix the API_SPEC.md pagination drift by moving pagination documentation into the OpenAPI source of truth (services/api/openapi.yaml) and ensuring scripts/generate-api-spec.js emits a Pagination section from that spec, so regeneration preserves accurate pagination docs.

Addressed:

• Changed: scripts/generate-api-spec.js
• Represent pagination parameters (limit, offset, cursor, defaults, maximums) in services/api/openapi.yaml so they survive regeneration.
• Confirm/ensure scripts/generate-api-spec.js preserves or correctly regenerates the Pagination section from the OpenAPI spec.
• Re-running the generator must produce an API_SPEC.md that still contains accurate pagination documentation.

#1560 — docs/api-versioning.md and API_SPEC.md duplicate versioning/deprecation policy text with drift risk

Remove the duplicated API versioning/deprecation policy block from API_SPEC.md (the second instance at lines 43-60), keep a single versioning section, and replace inline sunset dates/version status with a link to docs/api-versioning.md as the single source of truth.

Addressed:

• Changed: API_SPEC.md, docs/api-versioning.md
• Remove the duplicate internal versioning blurb in API_SPEC.md (the second occurrence, lines 43-60), keeping exactly one instance.
• Make API_SPEC.md link to docs/api-versioning.md as the single source of truth for sunset dates and roadmap instead of restating dates inline.
• Ensure no sunset date or version status appears in more than one file (i.e., remove inline dates/status from API_SPEC.md, leaving them only in docs/api-versioning.md).

Changes

• IMPLEMENTATION_SUMMARY.md (delete)
• cliff.toml (modify)
• .github/workflows/protect-changelog.yml (modify)
• scripts/generate-api-spec.js (modify)
• API_SPEC.md (modify)
• docs/api-versioning.md (modify)

Approach

1. Consolidate or archive orphaned root-level IMPLEMENTATION_SUMMARY*/PR_*/WORKFLOW_HARDENING docs #1557 — Consolidate or archive orphaned root-level IMPLEMENTATION_SUMMARY*/PR_*/WORKFLOW_HARDENING docs (Changed: IMPLEMENTATION_SUMMARY.md)
2. CHANGELOG.md compare/commit/issue links point to defunct GitHub org popsman01 instead of solutions-plug #1558 — CHANGELOG.md compare/commit/issue links point to defunct GitHub org popsman01 instead of solutions-plug (Changed: cliff.toml, .github/workflows/protect-changelog.yml)
3. API_SPEC.md Pagination section is appended after the auto-generation marker and will be silently dropped on regen #1559 — API_SPEC.md Pagination section is appended after the auto-generation marker and will be silently dropped on regen (Changed: scripts/generate-api-spec.js)
4. docs/api-versioning.md and API_SPEC.md duplicate versioning/deprecation policy text with drift risk #1560 — docs/api-versioning.md and API_SPEC.md duplicate versioning/deprecation policy text with drift risk (Changed: API_SPEC.md, docs/api-versioning.md)

Issues

Closes #1557
Closes #1558
Closes #1559
Closes #1560

[drips-wave]

@bytescape30 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits