Charon/docs/plans/archive/propagation_workflow_update.md

# Plan: Refine Propagation Workflow to Enforce Strict Hierarchy (Pittsburgh Model)

## 1. Introduction
This plan outlines the update of the `.github/workflows/propagate-changes.yml` workflow. The goal is to enforce a strict hierarchical propagation strategy ("The Pittsburgh Model") where changes flow downstream from `main` to `development`, and then from `development` to leaf branches (`feature/*`, `hotfix/*`). This explicitly prevents "loop-backs" and direct updates from `main` to feature branches.

## 2. Methodology & Rules
**The Pittsburgh Model (Strict Hierarchy):**

1.  **Rule 1 (The Ohio River)**: `main` **ONLY** propagates to `development`.
    -   *Logic*: `main` is the stable release branch. Changes here (hotfixes, releases) must flow into `development` first.
    -   *Constraint*: `main` must **NEVER** propagate directly to `feature/*` or `hotfix/*`.

2.  **Rule 2 (The Point)**: `development` is the **ONLY** branch that propagates to leaf branches.
    -   *Logic*: `development` is the source of truth for active work. It aggregates `main` changes plus ongoing development.
    -   *Targets*: `feature/*` and `hotfix/*`.

3.  **Rule 3 (Loop Prevention)**: Determine the "source" PR to prevent re-propagation.
    -   *Problem*: When `feature/A` merges into `development`, we must not open a PR from `development` back to `feature/A`.
    -   *Mechanism*: Identify the source branch of the commit triggering the workflow and exclude it from targets.

## 3. Workflow Design

### 3.1. Branching Strategy Logic

| Trigger Branch | Source | Target(s) | Logic |
| :--- | :--- | :--- | :--- |
| `main` | `main` | `development` | Create PR `main` -> `development` |
| `development` | `development` | `feature/*`, `hotfix/*` | Create PR `development` -> `[leaf]` (Excluding changes source) |
| `feature/*` | - | - | No action (Triggers CI only) |
| `hotfix/*` | - | - | No action (Triggers CI only) |

### 3.2. Logic Updates Needed

**A. Strict Main Enforcement**
- Current logic likely does this, but we will explicitly verify `if (currentBranch === 'main') { propagate('development'); }` and nothing else.

**B. Development Distribution & Hotfix Inclusion**
- Update the branch listing logic to find both `feature/*` AND `hotfix/*` branches.
- Current code only looks for `feature/*`.

**C. Loop Prevention (The "Source Branch" Check)**
- **Trigger**: Script runs on push to `development`.
- **Action**:
  1. Retrieve the Pull Request associated with the commit sha using the GitHub API.
  2. If a merged PR exists for this commit, extract the source branch name (`head.ref`).
  3. Exclude this source branch from the list of propagation targets.

### 3.3. Technical Implementation Details
- **File**: `.github/workflows/propagate-changes.yml`
- **Action**: `actions/github-script`

**Pseudo-Code Update:**
```javascript
// 1. Get current branch
const branch = context.ref.replace('refs/heads/', '');

// 2. Rule 1: Main -> Development
if (branch === 'main') {
    await createPR('main', 'development');
    return;
}

// 3. Rule 2: Development -> Leafs
if (branch === 'development') {
    // 3a. Identify Source (Rule 3 Loop Prevention)
    // NOTE: This runs on push, so context.sha is the commit sha.
    let excludedBranch = null;
    try {
        const prs = await github.rest.repos.listPullRequestsAssociatedWithCommit({
            owner: context.repo.owner,
            repo: context.repo.repo,
            commit_sha: context.sha,
        });
        // Find the PR that was merged
        const mergedPr = prs.data.find(pr => pr.merged_at);
        if (mergedPr) {
             excludedBranch = mergedPr.head.ref;
             core.info(`Commit derived from merged PR #${mergedPr.number} (Source: ${excludedBranch}). Skipping back-propagation.`);
        }
    } catch (e) {
        core.info('Could not check associated PRs: ' + e.message);
    }

    // 3b. Find Targets
    const branches = await github.paginate(github.rest.repos.listBranches, {
        owner: context.repo.owner,
        repo: context.repo.repo,
    });

    const targets = branches
        .map(b => b.name)
        .filter(b => (b.startsWith('feature/') || b.startsWith('hotfix/')))
        .filter(b => b !== excludedBranch); // Exclude source

    // 3c. Propagate
    core.info(`Propagating to ${targets.length} branches: ${targets.join(', ')}`);
    for (const target of targets) {
        await createPR('development', target);
    }
}
```

## 4. Implementation Steps

1.  **Refactor `main` logic**: Ensure it returns immediately after propagating to `development` to prevent any fall-through.
2.  **Update `development` logic**:
    -   Add `hotfix/` to the filter regex.
    -   Implement the `listPullRequestsAssociatedWithCommit` call to identify the exclusion.
    -   Apply the exclusion to the target list.
3.  **Verify Hierarchy**:
    -   Confirm no path exists for `main` -> `feature/*`.

## 5. Acceptance Criteria
- [ ] Push to `main` creates a PR ONLY to `development`.
- [ ] Push to `development` creates PRs to all downstream `feature/*` AND `hotfix/*` branches.
- [ ] Push to `development` (caused by merge of `feature/A`) does **NOT** create a PR back to `feature/A`.
- [ ] A hotfix merged to `main` flows: `main` -> `development`, then `development` -> `hotfix/active-work` (if any exist).