bug: LLDs not archived to done/ when issues are completed

[martymcenroe]

Problem

When issues are closed as COMPLETED, their LLDs remain in docs/lld/active/ instead of being moved to docs/lld/done/.

Found 6 orphaned LLDs for completed issues:

• LLD-173 (closed 2026-02-04)
• LLD-176 (closed 2026-02-03)
• LLD-177 (closed 2026-02-03)
• LLD-190 (closed 2026-02-03)
• LLD-248 (closed 2026-02-04)
• LLD-257 (closed 2026-02-04)

Expected Behavior

When an issue is closed (either via PR merge with "Fixes #N" or manual close), the corresponding LLD should be moved from docs/lld/active/ to docs/lld/done/.

Root Cause

The finalize node in the requirements workflow doesn't have a post-merge hook to archive LLDs. This should either be:

1. A GitHub Action triggered on issue close
2. Part of the implementation workflow's cleanup node (N9)
3. A pre-commit hook that detects merged issues

Workaround

Manual move: mv docs/lld/active/LLD-{N}.md docs/lld/done/

[martymcenroe]

Solution Analysis

Option	Verdict
1. GitHub Action on issue close	✅ RECOMMENDED
2. Implementation workflow N9 node	❌ Only covers automated workflow completions
3. Pre-commit hook	❌ Wrong trigger point (before merge, not after close)

Why GitHub Action?

1. Complete coverage - Catches ALL issue closures:

   • PR merge with "Closes #N"
   • Manual close
   • API/bot closures

2. N7 already archives - The TDD workflow's finalize node already archives when workflow completes. The gap is non-workflow closures.

3. Separation of concerns - Archival is housekeeping, not implementation logic.

Proposed Implementation

Updated runbook (0909) to document current limitation and planned fix.

[martymcenroe]

Recommended Solution: GitHub Action

After analyzing all three options:

Option	Verdict
1. GitHub Action on issue close	✅ RECOMMENDED
2. Implementation workflow N9 node	❌ N7 already archives - gap is non-workflow closures
3. Pre-commit hook	❌ Wrong trigger (commits happen before merge)

Why GitHub Action?

1. Complete coverage - Catches ALL closure paths: PR merge with "Closes #N", manual close, API/bot closures
2. N7 already handles workflow completions - The gap is specifically non-workflow closures
3. Separation of concerns - Archival is housekeeping, not implementation logic

Proposed Implementation

# .github/workflows/archive-lld.yml
name: Archive LLD on Issue Close

on:
  issues:
    types: [closed]

jobs:
  archive:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Archive LLD if exists
        run: |
          ISSUE=${{ github.event.issue.number }}
          LLD="docs/lld/active/LLD-${ISSUE}.md"

          if [ -f "$LLD" ]; then
            mkdir -p docs/lld/done
            mv "$LLD" "docs/lld/done/"

            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add docs/lld/
            git commit -m "chore: archive LLD-${ISSUE} [skip ci]"
            git push
            echo "Archived LLD-${ISSUE}"
          else
            echo "No LLD found for issue ${ISSUE}"
          fi

Done

• ✅ Updated runbook 0909 v1.1 to document the limitation
• ✅ Committed: ecba6b2