<!-- Moved from docs/05-operations/backlog-gatekeeper.md to docs/working/archive/operations/backlog-gatekeeper.md on 2026-06-16 (docs reorg Phase 2) -->
# Backlog Gatekeeper Procedures

**Last Updated:** November 3, 2025
**Status:** Active (Phase 1B - Gatekeeper Enforcement)

---

## Overview

This document defines the procedures for enforcing **Rule 1 of the governance system**:

> **Rule 1:** Only approved governance workflows or the project owner may add items to the development backlog.

The gatekeeper system prevents unauthorized backlog access through automated enforcement and audit logging.

---

## Rule 1: Backlog Access Control

### Who Can Add to the Backlog?

**✅ ALLOWED:**

1. **Project Owner** (rajames440)
   - May manually add items directly to backlog
   - No approval required
   - Full discretionary authority

2. **Automated Workflows** (Approved governance processes)
   - ECO (Engineering Change Order) workflow
     - Always routes to backlog
     - Triggered by: ECO template + approval
   - CAPA (Corrective/Preventive Action) workflow
     - Routes to backlog if PM decides
     - Triggered by: CAPA template + approval + PM decision (`route:backlog` label)

**❌ NOT ALLOWED:**

- Direct label application by non-owners
- Manual backlog entry without governance template
- Bypassing ECO/CAPA workflows
- Creating backlog issues without proper approval chain
- Applying `route:backlog` label outside workflow context

---

## Enforcement Mechanism

### Gatekeeper Workflow

**File:** `.github/workflows/gatekeeper-backlog-enforcement.yml`

**Trigger:** Monitors for `route:backlog` label application

**Detection Logic:**

```
IF route:backlog label applied THEN:
  IF actor is owner (rajames440) THEN:
    ✓ ALLOW (owner has full discretionary authority)
  ELSE IF issue has approval labels (approved-by-projm, approved-by-qualm, etc.) THEN:
    ✓ ALLOW (went through proper workflow)
  ELSE IF issue is ECO (type:eco) THEN:
    ✓ ALLOW (ECO always goes to backlog)
  ELSE:
    ✗ BYPASS DETECTED → Trigger enforcement actions
```

### Bypass Detection & Response

When an unauthorized backlog access attempt is detected:

1. **Security Warning Comment** (Posted to original issue)
   - Explains the violation
   - References proper procedures
   - Instructs user on correct process
   - Links to governance documentation

2. **PM Notification** (Automatic)
   - PM assigned to issue
   - Ensures management awareness
   - Allows PM to follow up with user

3. **Incident Report Creation** (Automatic)
   - New IR issue created with evidence
   - Severity: MAJOR
   - Full audit trail documentation
   - Links to original issue

4. **Security Log Entry** (Automatic)
   - Event logged to `in_basket/SEC_LOG.adoc`
   - Immutable audit trail in governance repository
   - Timestamp, actor, method, and response recorded

---

## GitHub Permission Configuration

### Recommended Setup

Since GitHub's native permissions are limited, we use a layered approach:

#### Layer 1: Repository Access Control

**Team Structure:**
- `Core Contributors` - PM, QA Lead, Engineering Manager
  - Can create and modify any issue
  - Can apply workflow labels
- `Development Team` - Developers, Engineers
  - Can create issues (governance templates)
  - Cannot directly modify backlog-related labels
  - Must use proper workflows

#### Layer 2: Branch Protection (if using branches for backlog)

If backlog is tracked via git branch:
- Restrict direct commits to backlog branch
- Require PR and approval
- Enforce workflow checks before merge

#### Layer 3: Automated Enforcement (Currently Active)

**Gatekeeper Workflow** (primary enforcement)
- Detects label application violations
- Creates incidents for violations
- Logs to SEC_LOG.adoc
- Notifies PM
- **This is the active enforcement layer**

### GitHub Repository Settings

To support gatekeeper enforcement:

1. **GitHub Token Permissions**
   - Ensure `GITHUB_TOKEN` can:
     - Write to issues (add comments, labels)
     - Create new issues (for IR)
   - Current: ✓ Configured in workflow

2. **Workflow Permissions**
   - Enable "Allow GitHub Actions to create and approve pull requests"
   - Ensure workflow `contents: write` for SEC_LOG updates
   - Current: ✓ Configured in workflow

3. **Issue Labels**
   - Ensure these labels exist:
     - `type:ir` - For Incident Reports
     - `severity:major` - For incident severity
     - `security-violation` - For security-related incidents
     - `route:backlog` - For backlog routing
     - Approval labels: `approved-by-projm`, `approved-by-qualm`

---

## Procedures for Different User Types

### Project Owner (rajames440)

**Authority:** Full discretionary control of backlog

**Procedures:**

1. **Manual Backlog Addition** (When Needed)
   ```
   1. Create governance document issue (using template)
   2. Review and approve as needed
   3. Apply `route:backlog` label directly
   4. Gatekeeper recognizes owner → ALLOWS
   ```

2. **Governance Oversight**
   - Review gatekeeper bypass incidents regularly
   - Assess if education or access restrictions needed
   - Update procedures based on patterns

### Project Managers, QA Leads, Engineering Managers

**Authority:** Decision-makers for document routing

**Procedures:**

1. **Receive Approval Request**
   ```
   1. Document submitted using proper template
   2. PM/QA reviews and approves
   3. Apply approval label (approved-by-projm, approved-by-qualm)
   4. Wait for PM backlog vs vault decision request
   ```

2. **Make Routing Decision**
   ```
   1. Evaluate: "Will a developer work on this?"
   2. If YES: Apply `route:backlog` label
   3. If NO: Apply `route:vault` label
   4. Gatekeeper validates approval + label → ALLOWS
   ```

3. **Handle Bypass Incidents**
   - Review IR created by gatekeeper
   - Assess if user education needed
   - Contact violating user with guidance

### Development Team

**Authority:** Submit documents only through proper workflows

**Procedures:**

1. **Submitting Work Request**
   ```
   1. Use appropriate template (ECR, CAPA, etc.)
   2. Provide complete information
   3. Submit via GitHub issue
   4. Wait for approval workflow
   5. DO NOT apply backlog labels directly
   ```

2. **ECO Creation (After ECR Approval)**
   ```
   1. ECR → PM approves → Engineering Manager receives notification
   2. Engineering Manager creates ECO from approved ECR
   3. ECO template → ECO automatically routes to backlog
   4. Developer picks up from backlog
   ```

3. **CAPA Submission**
   ```
   1. CAPA template → Complete all required fields
   2. QA/PM reviews and approves
   3. PM decides: Backlog or Vault?
   4. If backlog: developer picks up
   5. If vault: routed to governance
   ```

---

## Workflow Examples

### Example 1: Authorized Backlog Addition (ECO)

```
Step 1: Engineering Manager receives approved ECR
Step 2: Creates ECO issue using eco.yml template
Step 3: Fills in related ECR reference, FMEA decision, priority
Step 4: ECO workflow automatically applies route:backlog label
Step 5: Gatekeeper sees:
        - Actor: workflow (actions/github-script)
        - Labels: type:eco, status:approved, route:backlog
        - Evidence: ECO has required structure
        → ALLOW (recognized as approved workflow)
Step 6: Item appears in backlog
Step 7: Developer picks up and works on implementation
```

**Result:** ✓ Authorized, backlog entry allowed

---

### Example 2: Unauthorized Backlog Addition (Bypass)

```
Step 1: Developer creates issue (e.g., "Add feature X")
Step 2: Developer applies route:backlog label
        (Trying to skip approval process)
Step 3: Gatekeeper detects:
        - Actor: developer (non-owner)
        - Labels: route:backlog (but no approval evidence)
        - No type:eco or approval labels found
        → BYPASS DETECTED
Step 4: Gatekeeper actions:
        ✓ Posts warning comment: "Use proper ECR/CAPA workflow"
        ✓ Assigns PM for review
        ✓ Creates IR issue: "Unauthorized Backlog Access"
        ✓ Logs to SEC_LOG.adoc: Timestamp, actor, method, action
Step 5: PM reviews incident
Step 6: PM contacts developer with guidance
Step 7: Developer resubmits using proper ECR workflow
```

**Result:** ✗ Unauthorized attempt detected, logged, and corrected

---

### Example 3: Authorized PM Routing Decision

```
Step 1: CAPA submitted using capa.yml template
Step 2: QA reviews and approves
        → Adds approved-by-qualm label
Step 3: Gatekeeper rule 2 triggers: "Request PM decision"
Step 4: PM receives decision request comment
        (Backlog = developer work vs Vault = documentation)
Step 5: PM evaluates: "Is this a bug that needs fixing?"
        Yes → PM applies route:backlog label
Step 6: Gatekeeper sees:
        - Actor: PM (rajames440 or delegated)
        - Labels: type:capa, approved-by-qualm, route:backlog
        - Evidence: Approval + PM decision
        → ALLOW
Step 7: Route-to-vault workflow checks:
        route:backlog → Don't route to vault, stays in backlog
Step 8: Developer picks up CAPA from backlog
```

**Result:** ✓ Authorized through approval + PM decision chain

---

## Audit Procedures

### SEC_LOG.adoc

**Location:** `/StarForth-Governance/in_basket/SEC_LOG.adoc`

**Contents:**
- Timestamp (UTC) of security event
- Event type (Unauthorized Backlog Access, etc.)
- User/actor who triggered event
- Reference (Original issue #NNN)
- Detailed description of violation
- Severity level (CRITICAL, MAJOR, MINOR, LOW)
- Action taken (IR created, PM notified)

**Access:**
- Version controlled in StarForth-Governance repo
- Immutable audit trail
- Updated by workflows automatically

### Incident Reports (IR)

**Created By:** Gatekeeper workflow

**Labels:** `type:ir`, `severity:major`, `security-violation`

**Contains:**
- Original violation details
- What the user did
- What the proper process should be
- Governance references
- Links to governance documentation

**Review:** PM reviews IR, contacts user, documents follow-up

---

## Troubleshooting

### Issue: "I applied `route:backlog` but got a warning"

**Likely Cause:** Missing approval labels or not following workflow

**Solution:**
1. Check if your issue has proper approval labels
2. If not, go back and request approval first
3. PM will handle routing decision
4. Let PM apply the `route:backlog` label

**Reference:** See "Procedures for Development Team" above

---

### Issue: "My ECO should have gone to backlog but got a vault warning"

**Likely Cause:** ECO issue missing required fields or type label

**Solution:**
1. Verify you used eco.yml template
2. Check that issue has `type:eco` label
3. Check that issue has `status:approved` label
4. Try re-applying `route:backlog` after template validation

**Contact:** PM (@rajames440) if issue persists

---

### Issue: "I'm the owner but still got a warning"

**Likely Cause:** Workflow logic issue or label timing

**Solution:**
1. Check that your GitHub username is exactly `rajames440`
2. Verify gatekeeper workflow has correct OWNER_USERNAME
3. Check workflow execution logs in GitHub Actions

**Reference:** Gatekeeper workflow: `.github/workflows/gatekeeper-backlog-enforcement.yml`

---

## Governance References

**Related Documents:**
- `GOVERNANCE_WORKFLOW_IMPLEMENTATION.md` - Full workflow details
- `GOVERNANCE_DOCUMENT_TYPE_SPECIFICATION.md` - Document types and routing
- `.github/workflows/gatekeeper-backlog-enforcement.yml` - Enforcement code
- `/StarForth-Governance/in_basket/SEC_LOG.adoc` - Audit trail

**Key Rules:**
- **Rule 1:** Only approved workflows or owner may add to backlog
- **Rule 2:** All governance documents require approval before routing
- **Rule 3:** PM makes backlog vs vault routing decision for conditional types

---

## Summary

| Aspect | Details |
|--------|---------|
| **Rule** | Only owner or approved workflows may add to backlog |
| **Owner Authority** | rajames440 has full discretionary backlog access |
| **Approved Workflows** | ECO (always), CAPA (if PM decides) |
| **Detection** | Gatekeeper monitors route:backlog label application |
| **Bypass Response** | Warning + IR creation + PM notification + Security logging |
| **Audit Trail** | SEC_LOG.adoc in in_basket (immutable) |
| **Access Control** | Layered: GitHub permissions + Gatekeeper enforcement |

**Status:** ✓ Enforcement Active (Ready for Use)