Skip to main content

Backend Validated State And Source Hashes Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add the missing intermediate lifecycle coverage and artifact provenance tracking required by the backend transition plan.

Architecture: Extend the existing backend stages with the smallest possible contract changes. Keep the current plan -> write -> maintenance -> distribution flow intact, but make lifecycle reporting richer and make stage outputs traceable to their inputs.

Tech Stack: Node.js, CommonJS modules, Vitest, gray-matter

Task 1: Add lifecycle states to planner and maintenance​

Files:

  • Modify: backend/lib/content/articleLifecycle.js

  • Modify: backend/stages/maintenance.js

  • Test: backend/stages/plan.test.js

  • Test: backend/stages/maintenance.test.js

  • Add missing lifecycle branches so planner can distinguish outlined from writer_ready, and maintenance can report validated before finalization.

  • Keep final article behavior unchanged unless tests prove a regression.

  • Update tests to assert the new lifecycle contract directly.

Task 2: Record source hashes for write, maintenance, and distribution​

Files:

  • Modify: backend/lib/artifacts.js

  • Modify: backend/stages/write.js

  • Modify: backend/stages/maintenance.js

  • Modify: backend/stages/distribution.js

  • Test: backend/stages/write.test.js

  • Test: backend/stages/maintenance.test.js

  • Test: backend/stages/distribution.test.js

  • Add a small shared file-hash helper in backend runtime utilities.

  • Record planner artifact and outline hashes in write.

  • Record draft or writer-manifest provenance in maintenance.

  • Record finalized article provenance in distribution.

  • Update tests to assert concrete sourceHashes keys instead of {}.

Task 3: Verify the backend contract​

Files:

  • Test: backend/bin/run.test.js

  • Test: backend/stages/e2e.test.js

  • Test: backend/stages/worker.test.js

  • Run targeted backend Vitest coverage for runner and stage tests.

  • Confirm no existing flow regressed while the richer lifecycle and source hashes were added.