docs: seed revised dual-track workflow plan
This commit is contained in:
agentson
211
docs/plans/2026-03-02-dual-track-workflow-execution-plan.md
Normal file
211
docs/plans/2026-03-02-dual-track-workflow-execution-plan.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Dual-Track Workflow Execution Plan (Revised)
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Re-seed workflow planning from a clean base branch (not the temporary branch), then execute isolated `86` and `80` tracks with real-operation-confirmed closeout and related Gitea issue closure.
|
||||
|
||||
**Architecture:** Start from `feature/v3-session-policy-stream` and create `base/ouroboros-workflow-20260302`. Bring only two workflow plan docs as one squashed seed commit. Branch `task/86...` and `task/80...` from that base with strict file-scope separation. For `80`, update audit only after real-operation confirmation, then close related Gitea issues (children before parent). Final promotion happens by merging the validated stream to `main`.
|
||||
|
||||
**Tech Stack:** Git CLI, Gitea (`tea`) issue/PR workflow, Markdown docs (`docs/ouroboros`, `docs/plans`)
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Freeze temporary branch and identify export scope
|
||||
|
||||
**Files:**
|
||||
- Modify: none
|
||||
- Create: none
|
||||
- Test: none
|
||||
|
||||
**Step 1: Inspect temporary branch state**
|
||||
|
||||
Run: `git status --short --branch`
|
||||
Expected: current temporary branch with local changes listed.
|
||||
|
||||
**Step 2: Preserve changes using stash (recommended)**
|
||||
|
||||
Run: `git stash push -u -m "tmp-before-workflow-reseed-2026-03-02"`
|
||||
Expected: stash created with tracked/untracked changes.
|
||||
|
||||
**Step 3: Define transferable artifacts**
|
||||
|
||||
Run: keep only these for reseed:
|
||||
- `docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md`
|
||||
- `docs/plans/2026-03-02-dual-track-workflow-execution-plan.md`
|
||||
Expected: transfer scope fixed to two files.
|
||||
|
||||
**Step 4: Verify clean working tree**
|
||||
|
||||
Run: `git status --short --branch`
|
||||
Expected: no local changes.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
# no commit in this task (stash-only preservation)
|
||||
```
|
||||
|
||||
### Task 2: Create clean official base and seed one commit
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md`
|
||||
- Modify: `docs/plans/2026-03-02-dual-track-workflow-execution-plan.md`
|
||||
- Test: none
|
||||
|
||||
**Step 1: Switch to canonical base**
|
||||
|
||||
Run: `git checkout feature/v3-session-policy-stream`
|
||||
Expected: branch switch successful.
|
||||
|
||||
**Step 2: Update local base**
|
||||
|
||||
Run: `git pull --ff-only origin feature/v3-session-policy-stream`
|
||||
Expected: up-to-date or fast-forward update.
|
||||
|
||||
**Step 3: Create staging base branch**
|
||||
|
||||
Run: `git checkout -b base/ouroboros-workflow-20260302`
|
||||
Expected: new branch created from updated feature base.
|
||||
|
||||
**Step 4: Restore only two plan docs from temporary branch commits**
|
||||
|
||||
Run (example): `git checkout <temp-branch> -- docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md docs/plans/2026-03-02-dual-track-workflow-execution-plan.md`
|
||||
Expected: only two files restored in working tree.
|
||||
|
||||
**Step 5: Create one squashed seed commit**
|
||||
|
||||
Run: `git add docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md docs/plans/2026-03-02-dual-track-workflow-execution-plan.md && git commit -m "docs: seed revised dual-track workflow plan"`
|
||||
Expected: single commit with two files only.
|
||||
|
||||
**Step 6: Verify seed scope**
|
||||
|
||||
Run: `git show --name-only --oneline HEAD`
|
||||
Expected: exactly the two plan docs listed.
|
||||
|
||||
**Step 7: Push official base**
|
||||
|
||||
Run: `git push -u origin base/ouroboros-workflow-20260302`
|
||||
Expected: remote tracking set.
|
||||
|
||||
### Task 3: Open Track A (`86`) branch and initial PR
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/ouroboros/86_peak_probability_model_plan.md`
|
||||
- Test: none
|
||||
|
||||
**Step 1: Create Track A branch**
|
||||
|
||||
Run: `git checkout -b task/86-peak-probability-plan`
|
||||
Expected: branch created from official base.
|
||||
|
||||
**Step 2: Stage only `86` document**
|
||||
|
||||
Run: `git add docs/ouroboros/86_peak_probability_model_plan.md`
|
||||
Expected: only `86` doc staged.
|
||||
|
||||
**Step 3: Commit initial PR seed**
|
||||
|
||||
Run: `git commit -m "docs: seed peak probability model plan (#86)"`
|
||||
Expected: one-document commit.
|
||||
|
||||
**Step 4: Push branch**
|
||||
|
||||
Run: `git push -u origin task/86-peak-probability-plan`
|
||||
Expected: remote branch created.
|
||||
|
||||
**Step 5: Open PR-A**
|
||||
|
||||
Run: `tea pr create --base base/ouroboros-workflow-20260302 --head task/86-peak-probability-plan --title "docs: seed peak probability model plan (#86)" --description "Initial planning PR for iterative concretization."`
|
||||
Expected: PR URL returned.
|
||||
|
||||
### Task 4: Open Track B (`80`) branch for operation-confirmed closeout
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/ouroboros/80_implementation_audit.md`
|
||||
- Test: operation observation evidence (outside unit-test scope)
|
||||
|
||||
**Step 1: Return to staging base**
|
||||
|
||||
Run: `git checkout base/ouroboros-workflow-20260302`
|
||||
Expected: branch switch successful.
|
||||
|
||||
**Step 2: Create Track B branch**
|
||||
|
||||
Run: `git checkout -b task/80-implementation-audit-closeout`
|
||||
Expected: branch created.
|
||||
|
||||
**Step 3: Apply closeout edits only after real-operation confirmation**
|
||||
|
||||
Run: edit `docs/ouroboros/80_implementation_audit.md`
|
||||
Expected: status/evidence sections updated with observed behavior, confirmation timestamp, and operational proof summary.
|
||||
|
||||
**Step 4: Commit closeout update**
|
||||
|
||||
Run: `git add docs/ouroboros/80_implementation_audit.md && git commit -m "docs: close out implementation audit items after operation confirmation (#80)"`
|
||||
Expected: single-scope commit.
|
||||
|
||||
**Step 5: Push and open PR-B**
|
||||
|
||||
Run: `git push -u origin task/80-implementation-audit-closeout`
|
||||
Expected: remote branch created.
|
||||
|
||||
Run: `tea pr create --base base/ouroboros-workflow-20260302 --head task/80-implementation-audit-closeout --title "docs: close out implementation audit items (#80)" --description "Closeout based on real-operation confirmation."`
|
||||
Expected: PR URL returned.
|
||||
|
||||
### Task 5: Close related Gitea issues after `80` confirmation
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/ouroboros/80_implementation_audit.md` (reference linkage only)
|
||||
- Test: issue parent-child completeness check
|
||||
|
||||
**Step 1: Build related issue set from updated `80` audit**
|
||||
|
||||
Run: parse issue references from `80` updated sections.
|
||||
Expected: target open issue list prepared.
|
||||
|
||||
**Step 2: Close child issues first**
|
||||
|
||||
Run: `tea issues close <child-issue-number>` for each confirmed child.
|
||||
Expected: all qualifying child issues closed.
|
||||
|
||||
**Step 3: Close parent issues only when all children are closed**
|
||||
|
||||
Run: `tea issues close <parent-issue-number>`
|
||||
Expected: parent closes only after dependency check passes.
|
||||
|
||||
**Step 4: Record closure summary in PR comment**
|
||||
|
||||
Run: add PR comment with closed issue IDs and parent-child resolution note.
|
||||
Expected: auditable trace for closeout.
|
||||
|
||||
### Task 6: Validate branch hygiene and merge path
|
||||
|
||||
**Files:**
|
||||
- Modify: none
|
||||
- Test: git diff/log checks
|
||||
|
||||
**Step 1: Verify PR-A scope**
|
||||
|
||||
Run: `git diff --name-only base/ouroboros-workflow-20260302...task/86-peak-probability-plan`
|
||||
Expected: only `docs/ouroboros/86_peak_probability_model_plan.md` (and intentional related plan files if any).
|
||||
|
||||
**Step 2: Verify PR-B scope**
|
||||
|
||||
Run: `git diff --name-only base/ouroboros-workflow-20260302...task/80-implementation-audit-closeout`
|
||||
Expected: only `docs/ouroboros/80_implementation_audit.md` (and intentional related plan files if any).
|
||||
|
||||
**Step 3: Merge both PRs into staging base**
|
||||
|
||||
Run: GitHub merge flow for PR-A and PR-B
|
||||
Expected: staging base includes both tracks without cross-file contamination.
|
||||
|
||||
**Step 4: Promote validated stream to `main`**
|
||||
|
||||
Run: open PR from `feature/v3-session-policy-stream` (or its validated promotion branch) to `main`
|
||||
Expected: merge-based history preservation with no cherry-pick/rebase surgery.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
# no additional commit required in this task
|
||||
```
|
||||
@@ -0,0 +1,99 @@
|
||||
# Ouroboros Dual-Track Workflow Design (Revised)
|
||||
|
||||
**Date:** 2026-03-02
|
||||
**Scope:** `docs/ouroboros/86_peak_probability_model_plan.md` and `docs/ouroboros/80_implementation_audit.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Goal
|
||||
|
||||
Prevent work loss and history contamination while running two parallel tracks, while correcting an invalid starting condition (design commits created on a disposable temporary branch):
|
||||
|
||||
- Track A: open and iterate the `86` plan as a dedicated PR.
|
||||
- Track B: finalize `80` only after real-operation behavior is confirmed, then reflect completion and close related Gitea open issues.
|
||||
|
||||
---
|
||||
|
||||
## 2. Constraints and Current Context
|
||||
|
||||
- Current temporary branch is disposable and must not remain the authoritative base.
|
||||
- Canonical base line for current work is `feature/v3-session-policy-stream`.
|
||||
- Final integration strategy is to merge the full `feature/v3-session-policy-stream` line into `main` after operation-level validation is complete.
|
||||
|
||||
---
|
||||
|
||||
## 3. Approaches Considered
|
||||
|
||||
1. Keep using temporary branch and continue from existing design commits.
|
||||
2. Create a clean base from `feature/v3-session-policy-stream` and move only plan artifacts as one commit (recommended).
|
||||
3. Split into two fresh bases (`86` and `80` separately) immediately.
|
||||
|
||||
Recommendation rationale:
|
||||
|
||||
- Approach 2 removes temporary-branch contamination risk.
|
||||
- It preserves clean lineage with a single "official starting point" commit.
|
||||
- It keeps downstream split for `86` and `80` straightforward.
|
||||
|
||||
---
|
||||
|
||||
## 4. Approved Branch and PR Topology
|
||||
|
||||
- Long-lived source baseline: `feature/v3-session-policy-stream`
|
||||
- New official base: `base/ouroboros-workflow-20260302` (from `feature/v3-session-policy-stream`)
|
||||
- Official base contains only two workflow plan docs squashed into one commit.
|
||||
- Track A branch: `task/86-peak-probability-plan` (from official base)
|
||||
- Track B branch: `task/80-implementation-audit-closeout` (from official base)
|
||||
|
||||
PR direction:
|
||||
|
||||
- PR-A (`86`): `task/86-peak-probability-plan -> base/ouroboros-workflow-20260302`
|
||||
- PR-B (`80`): `task/80-implementation-audit-closeout -> base/ouroboros-workflow-20260302`
|
||||
- Final integration: `feature/v3-session-policy-stream` line merged into `main`
|
||||
|
||||
---
|
||||
|
||||
## 5. Completion Criteria per Track
|
||||
|
||||
### Track A (`86`)
|
||||
|
||||
- Open initial PR early with the planning document.
|
||||
- Continue iterative concretization in follow-up commits on the same branch.
|
||||
|
||||
### Track B (`80`)
|
||||
|
||||
- Do not close based on test-command artifacts alone.
|
||||
- Close only when modified behavior is confirmed in real operation.
|
||||
- Update `80_implementation_audit.md` with:
|
||||
- observed behavior changes,
|
||||
- confirmation timing,
|
||||
- operation-side evidence summary.
|
||||
- After `80` real-operation confirmation and doc update, close related Gitea open issues immediately (same phase).
|
||||
- Parent issues close only when all child issues are confirmed closed.
|
||||
|
||||
---
|
||||
|
||||
## 6. Loss-Prevention Rules
|
||||
|
||||
- Preserve temporary-branch unmerged changes first (stash or archival commit).
|
||||
- Exclude `workflow/session-handover.md` and `docs/ouroboros/86_peak_probability_model_plan.md` from official base-seeding commit.
|
||||
- Enforce file-scope separation:
|
||||
- PR-A should avoid `80` edits.
|
||||
- PR-B should avoid `86` edits.
|
||||
- Keep commit messages scoped to one track per commit.
|
||||
|
||||
---
|
||||
|
||||
## 7. Merge Strategy Decision
|
||||
|
||||
- For this workflow, prefer merge-based lineage preservation.
|
||||
- Because the final promotion unit is the full `feature/v3-session-policy-stream` stream, avoid unnecessary cherry-pick/rebase-surgery unless a contamination incident occurs.
|
||||
|
||||
---
|
||||
|
||||
## 8. Immediate Next Actions
|
||||
|
||||
1. Seed `base/ouroboros-workflow-20260302` from `feature/v3-session-policy-stream` with one squashed workflow-doc commit.
|
||||
2. Verify seed commit file scope contains only two plan docs.
|
||||
3. Create and open PR-A for `86`.
|
||||
4. Complete real-operation confirmation for `80`, update audit doc, then close related Gitea issues (children first, then parent).
|
||||
5. Merge validated `feature/v3-session-policy-stream` line into `main`.
|
||||
Reference in New Issue
Block a user