diff --git a/docs/plans/2026-03-02-dual-track-workflow-execution-plan.md b/docs/plans/2026-03-02-dual-track-workflow-execution-plan.md new file mode 100644 index 0000000..b047193 --- /dev/null +++ b/docs/plans/2026-03-02-dual-track-workflow-execution-plan.md @@ -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 -- 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 ` 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 ` +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 +``` diff --git a/docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md b/docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md new file mode 100644 index 0000000..6aa5017 --- /dev/null +++ b/docs/plans/2026-03-02-ouroboros-dual-track-workflow-design.md @@ -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`.