update-project-docs

Update Project Docs

Overview

Keep ApprovalFlow's docs in sync with completed work. Use this as a final task gate before handoff, after verification evidence is known and before summarizing the result.

Workflow

1. Identify the completed task or feature group and the branch context:

   • V1 baseline uses docs/planning/BASELINE_PLAN.md.
   • V2 architecture work uses docs/planning/V2_PLAN.md.

2. Always check the relevant plan file:

   • Update it when task status changed.
   • If it already reflects the completed work, leave it unchanged but mention that it was checked.
   • Do not skip the plan target just because other docs were updated.

3. Update status language in the relevant plan file:

   • Use the established style, for example **Status: ✅ complete.**, **Status: ⬜ pending.**, or future / deferred.
   • Mark only work that was actually implemented and verified.
   • Keep planned or target architecture explicitly labeled as planned/future.

4. Sweep impacted docs, not every file blindly. Check and update as applicable:

   • README.md
   • ARCHITECTURE.md
   • ADR.md and assigned ADR wording
   • docs/RECORDING_SCRIPT.md
   • docs/evidence/
   • command references, renamed files, diagrams, sequence flows, and status tables

5. Remove stale references:

   • old file names such as renamed status docs
   • obsolete commands or flags
   • flow diagrams that imply an old sync/async boundary
   • claims that future work is already implemented

6. Preserve authority boundaries:

   • Do not edit assignment sources.
   • Do not edit docs/PRODUCT_DILEMMA.md unless explicitly assigned.
   • Do not weaken accepted requirements, ADR decisions, AI/payment authority boundaries, or verification expectations.

7. Verify the documentation sweep:

   • Use rg for old names, old commands, old task labels, and stale event names.
   • Use git diff to confirm the docs say only what the task actually changed.
   • Run tests only when docs changes include executable examples, scripts, generated evidence, or behavior claims that need fresh proof.

Status Style

Prefer the same concise markers used in the ApprovalFlow plans:

• **Status: ✅ complete.**
• **Status: ⬜ pending.**
• **Status: ⬜ partial / future.**
• future / deferred

Add a short explanation after the marker when the distinction matters, especially for planned architecture versus current implementation.

Common Checks

• If a task changed service flow, update architecture diagrams and sync/async wording.
• If a task changed verification, update plan gates, README commands, demo guide, and evidence references.
• If a task was split or renamed, update task maps, plan entries, and references.
• After every completed task, check the relevant plan even if the task mainly changed code.
• If a file was renamed, grep the repo for the old path and update all references.
• If live/manual verification was used, label it as live/manual and do not imply CI coverage.