Skip to main content

ICW Implementation Plan – E7:S01:T06 (Update Changelog Workflow)

1. Overview​

Manual UCW process replacing missing changelog governance. Execution focuses on drafting the workflow spec, producing evidence-driven checklists, updating documentation, and wiring CI verification without introducing automated trimming scripts.

2. Milestones & Timeline (5 days)​

PhaseDay(s)OwnerDeliverables
P0 – Discovery0-1Documentation AgentDecision log (no-script stance), changelog inventory, archive gap notes
P1 – Specification1-2Documentation AgentSpec + checklist template, CI hook contract, governance addendum
P2 – Test Design & Dry Run2-3Release Engineer + Documentation AgentTest design doc, tabletop dry run results, evidence samples
P3 – Documentation & Runbook Updates3-4Documentation AgentRelease-runbook updates, Story/Task metadata, kanban narrative, FR references
P4 – Handoff & Monitoring4-5UKW Agent + AuditorUCW log onboarding, CI job enablement, audit schedule

3. Phase Details​

Phase 0 – Discovery​

  • Read current CHANGELOG.md + archives to gauge drift.
  • Capture user mandate (manual trimming only) into decision record stored alongside spec.
  • Identify existing validators (ordering, markdownlint) to reuse later.

Phase 1 – Specification​

  • Finalize ICW-E7S01T06-specification.md (done) and attach checklist template.
  • Define evidence requirements (UCW log file, diff artifact, reviewer sign-off).
  • Draft governance addendum for release runbook + FR-057 cross-links.

Phase 2 – Test Design & Dry Run​

  • Publish ICW-E7S01T06-test-design.md (done) with UCW-T01–T04 scenarios.
  • Run tabletop dry run on current changelog; store outputs in docs/maintenance/logs/ucw/UCW-DRYRUN-20260315.md.
  • Validate CI read-only script detects missing evidence but never edits files.

Phase 3 – Documentation & Runbook Updates​

  • Update docs/maintenance/release-runbook.md (Changelog Stewardship section) to embed UCW steps.
  • Annotate Story 001 Task T06 checklist with artifact links + version v0.7.1.6+1.
  • Update kanban board narrative to show UCW plan approval & artifacts.
  • Extend FR-057 references to include UCW deliverables and manual policy guidance.

Phase 4 – Handoff & Monitoring​

  • Create docs/maintenance/logs/ucw/README.md describing log retention & sign-off expectations.
  • UKW Agent schedules monthly audit block referencing perpetual lint Task (E7:S01:T05).
  • Wire CI job ucw-verification into RW pipeline (read-only guard) and document rollback procedure if evidence missing.

4. Resource & Ownership​

  • Documentation Agent: Lead spec, checklist, manual operations, archive upkeep.
  • Release Engineer: Validate ordering, integrate CI verification, ensure RW gating.
  • UKW Agent/Auditor: Monitor compliance, manage backlog tie-ins (perpetual Tasks).

5. Risks & Mitigations​

  • Time pressure skip: RW Step 8 blocked without UCW log; runbook highlights gating.
  • Evidence drift: CI job checks for log + diff before RW continues.
  • Retention threshold disagreements: Document change request path; default 20 stored in config.

6. Dependencies​

  • FR-057 Update Changelog Workflow (now referencing manual UCW).
  • Release Runbook & RW validations (Step 8 gating).
  • Perpetual markdown Task E7:S01:T05 for global doc hygiene.

7. Completion Criteria​

  • Spec, test design, implementation plan stored under docs/implementation-cycles/ with lifecycle metadata.
  • Release-runbook, FR-057, Story/Task docs updated referencing UCW artifacts.
  • CI verification job operational and documented.
  • First UCW dry run recorded with evidence, ready for next RW cycle.