Charon/docs/plans/current_spec.md

Current Specification

Status: 🔴 ACTIVE - Docs-to-Issues CI Skip Investigation Last Updated: 2026-01-11 Current Work: Resolving PR #461 CI check failures caused by docs-to-issues workflow

---

Active Investigation: Docs-to-Issues CI Skip Problem

Priority: 🔴 HIGH - Blocking PR validation Reported: PR #461 Reference: 8bd0f9433a

Problem Statement

The docs-to-issues.yml workflow is preventing CI checks from appearing on PRs when it runs, breaking the PR review and merge process.

Observed Behavior:

1. When docs-to-issues workflow triggers on a PR, it creates an automated commit
2. The commit message contains [skip ci] flag
3. GitHub interprets this as "skip ALL CI workflows for this commit"
4. No required status checks run on the PR
5. PR cannot be properly validated or merged

Impact:

• Blocks PR merges - Required status checks never run
• Breaks validation pipeline - Tests, linting, security scans don't execute
• Defeats CI/CD purpose - Changes go unverified

Root Cause Analysis

Workflow Location: .github/workflows/docs-to-issues.yml

Problem Line: Line 346

git commit -m "chore: move processed issue files to created/ [skip ci]"

Why [skip ci] Exists: The workflow uses [skip ci] to prevent an infinite loop:

1. Workflow runs on push to docs/issues/**/*.md
2. Creates GitHub issues from markdown files
3. Moves processed files to docs/issues/created/
4. Commits the file moves back to the same branch
5. Without [skip ci], this commit would trigger the workflow again → infinite loop

GitHub's [skip ci] Behavior:

• Scope: [skip ci] skips ALL workflows triggered by push events for that commit
• Alternative Syntax: [ci skip], [no ci], [skip actions], ***NO_CI***
• Documentation: https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs

Why This Breaks PRs:

• GitHub requires status checks to pass on the latest commit of a PR
• When the latest commit has [skip ci], the required workflows don't run
• GitHub shows "Waiting for status to be reported" indefinitely
• PR is blocked from merging

Current Workflow Behavior

Trigger Conditions:

on:
  push:
    branches:
      - main
      - development
      - feature/**
    paths:
      - 'docs/issues/**/*.md'
      - '!docs/issues/created/**'

Process Flow:

1. Detects new/modified markdown files in docs/issues/
2. Parses frontmatter (title, labels, assignees)
3. Creates GitHub issues via API
4. Moves processed files to docs/issues/created/YYYYMMDD-filename.md
5. Commits file moves with [skip ci]
6. Pushes commit to same branch

Protection Mechanism:

• if: github.actor != 'github-actions[bot]' - Prevents bot-triggered loops
• [skip ci] - Prevents push-triggered loops

Investigation Results

Other Workflows That Commit:

1. auto-versioning.yml (Line 69):

   • Creates and pushes tags: git push origin "${TAG}"
   • No [skip ci] - but only pushes tags, not commits
   • Tags don't trigger on: push workflows

2. propagate-changes.yml:

   • Creates PRs instead of committing directly
   • No [skip ci] - uses PR mechanism instead
   • Avoids the problem entirely

3. auto-changelog.yml:

   • Uses release-drafter action (no direct commits)
   • No [skip ci] - doesn't create commits

Pattern Analysis:

• ✅ Best Practice: Create separate PRs for automated changes (propagate-changes)
• ✅ Alternative: Use tags instead of commits (auto-versioning)
• ❌ Anti-pattern: Direct commits with [skip ci] (docs-to-issues)

Solution Options

Option 1: Remove [skip ci] + Add Path Filter (RECOMMENDED)

Changes:

1. Remove [skip ci] from commit message
2. Add path exclusion to workflow trigger:

   on:
     push:
       paths:
         - 'docs/issues/**/*.md'
         - '!docs/issues/created/**'  # Already present
   

3. Rely on existing github.actor != 'github-actions[bot]' guard

Pros:

• ✅ CI checks run normally on PRs
• ✅ Still prevents infinite loops (path filter + actor guard)
• ✅ Minimal code changes
• ✅ No workflow complexity increase

Cons:

• ⚠️ Adds one extra workflow run per docs-to-issues execution (the file move commit)
• ⚠️ Slight increase in Actions minutes usage (~30 seconds per run)

Risk Assessment: LOW

• Path filter already excludes docs/issues/created/**
• Actor guard prevents bot loops
• Double protection against infinite loops

Option 2: Create Separate PR for File Moves

Changes:

1. Instead of committing directly, create a PR with file moves
2. Use actions/github-script to create PR via API
3. Auto-merge PR or leave for manual review

Pros:

• ✅ No [skip ci] needed
• ✅ CI runs on all commits
• ✅ Audit trail via PRs
• ✅ Follows propagate-changes pattern

Cons:

• ❌ High complexity - requires significant refactoring
• ❌ Creates many auto-PRs (noise)
• ❌ Slower - PR review process adds delay
• ❌ Requires CPMP_TOKEN or similar for auto-merge

Risk Assessment: MEDIUM

• More moving parts
• Could create PR spam
• Requires additional token management

Option 3: Don't Commit File Moves

Changes:

1. Remove the "Move processed files" and "Commit moved files" steps
2. Let files remain in docs/issues/ after processing
3. Add .gitignore for processed files or manual cleanup

Pros:

• ✅ No [skip ci] needed
• ✅ Simplest solution
• ✅ CI runs normally

Cons:

• ❌ Processed files accumulate in docs/issues/
• ❌ No clear separation of pending vs. completed
• ❌ Requires manual cleanup or gitignore maintenance
• ❌ Loses historical record of when issues were created

Risk Assessment: MEDIUM

• Defeats organizational purpose of the workflow
• Clutters the docs/issues directory

Option 4: Use [skip ci] Only on Main/Development

Changes:

1. Add conditional to only skip CI on protected branches:

   - name: Commit moved files
     run: |
       if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/development" ]]; then
         git commit -m "chore: move processed issue files [skip ci]"
       else
         git commit -m "chore: move processed issue files"
       fi
   

Pros:

• ✅ CI runs on PRs (feature branches)
• ✅ Skips CI on main/dev (reduces noise)
• ✅ Balanced approach

Cons:

• ⚠️ Still causes double runs on feature branches
• ⚠️ Adds branch-specific logic complexity

Risk Assessment: LOW

• Good compromise solution
• Preserves optimization on main branches
• Enables validation on PRs

Recommended Solution: Option 1 (Remove [skip ci])

Justification:

1. Solves the problem completely - CI checks will run on PRs
2. Low risk - Multiple safeguards prevent infinite loops
3. Minimal changes - One-line modification
4. Performance impact is negligible - ~30 seconds extra per run
5. Aligns with CI/CD principles - All changes should be validated

Implementation Steps:

1. Modify .github/workflows/docs-to-issues.yml line 346:

   # BEFORE:
   git commit -m "chore: move processed issue files to created/ [skip ci]"
   
   # AFTER:
   git commit -m "chore: move processed issue files to created/"
   

2. Verify safeguards are in place:

   • ✅ Line 45: if: github.actor != 'github-actions[bot]'
   • ✅ Lines 11-12: Path exclusions for docs/issues/created/**

3. Test on feature branch:

   • Create test markdown file in docs/issues/test-issue.md
   • Push to feature branch
   • Verify workflow runs and creates issue
   • Verify file moves to created/
   • Verify commit triggers ONE more workflow run
   • Verify second run skips (no files in docs/issues/)
   • Verify CI checks appear on PR

4. Monitor for infinite loops:

   • Check workflow run history
   • Confirm only 2 runs per docs change (original + file move)
   • No cascading triggers

Success Criteria

• ✅ CI checks run and appear on PRs when docs-to-issues workflow executes
• ✅ No infinite workflow loops occur
• ✅ File moves still happen correctly
• ✅ Issues are still created properly
• ✅ PR #461 can be validated and merged
• ✅ No increase in workflow failures

Rollback Plan

If Option 1 causes problems:

1. Revert commit (one-line change)
2. Implement Option 4 (conditional [skip ci]) as fallback
3. Re-test on feature branch

Documentation Updates

After implementation:

• Update .github/workflows/docs-to-issues.yml with inline comments
• Document decision in implementation summary
• Update CHANGELOG.md
• Add note to workflow documentation (if exists)

---

Completed Work

CI/CD Workflow Fixes (2026-01-11) ✅

Status: Complete - All documentation finalized

The CI workflow investigation and documentation has been completed. Both issues were determined to be false positives or expected GitHub behavior with no security gaps.

Final Documentation:

• Implementation Summary: docs/implementation/CI_WORKFLOW_FIXES_2026-01-11.md
• QA Report: docs/reports/qa_report.md
• Archived Plan: docs/plans/archive/GITHUB_SECURITY_WARNING_RESOLUTION_PLAN_2026-01-11.md

Changes Made:

• ✅ Workflow files documented with explanatory comments
• ✅ SECURITY.md updated with comprehensive scanning coverage
• ✅ CHANGELOG.md updated with workflow migration entry
• ✅ Implementation summary created
• ✅ All validation tests passed (CodeQL, Trivy, pre-commit)
• ✅ Planning docs archived

Merge Status: ✅ SAFE TO MERGE - Zero security gaps, fully documented

---

Active Projects

Ready for next task

---

Recently Completed

Workflow Orchestration Fix (2026-01-11)

Successfully fixed workflow orchestration issue where supply-chain-verify was running before docker-build completed, causing verification to skip on PRs.

Documentation:

• Implementation Summary: docs/implementation/WORKFLOW_ORCHESTRATION_FIX.md
• QA Report: docs/reports/qa_report_workflow_orchestration.md
• Archived Plan: docs/plans/archive/workflow_orchestration_fix_2026-01-11.md

Status: ✅ Complete - Deployed to production

---

Grype SBOM Remediation (2026-01-10)

Successfully resolved CI/CD failures in the Supply Chain Verification workflow caused by Grype SBOM format mismatch.

Documentation:

• Implementation Summary: docs/implementation/GRYPE_SBOM_REMEDIATION.md
• QA Report: docs/reports/qa_report.md
• Archived Plan: docs/plans/archive/grype_sbom_remediation_2026-01-10.md

Status: ✅ Complete - Deployed to production

---

Guidelines for Creating New Specs

When starting a new project, create a detailed specification in this file following the Spec-Driven Workflow v1 format.

Required Sections

1. Problem Statement - What issue are we solving?
2. Root Cause Analysis - Why does the problem exist?
3. Solution Design - How will we solve it?
4. Implementation Plan - Step-by-step tasks
5. Testing Strategy - How will we validate success?
6. Success Criteria - What defines "done"?

Archiving Completed Specs

When a specification is complete:

1. Create implementation summary in docs/implementation/
2. Move spec to docs/plans/archive/ with timestamp
3. Update this file with completion notice

---

Archive Location

Completed and archived specifications can be found in:

• docs/plans/archive/

---

Note: This file should only contain ONE active specification at a time. Archive completed work before starting new projects.