Alpha Release Tracking Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: make v0.1.0-alpha.1 executable from GitHub Issues by closing release-scope decisions, proving the final remote contributor validation lane, validating the docs/demo experience, and preparing the tag only after evidence exists.

Architecture: GitHub Issues are the source of truth for release blockers; this plan is the execution map. docs/releases/v0.1.0-alpha.1-checklist.md is the tag gate, and docs/validation/ stores durable evidence from commands, workflow URLs, and manual walkthrough notes. Release decisions must move issues out of alpha-blocker or close them; unresolved alpha-blocker issues block the tag.

Tech Stack: GitHub Issues and milestones, GitHub Actions, DevPod remote contributor validation workspace, Kind, Helm, Kubernetes, Python/uv/pytest, Starlight docs, Customer 360 demo, Dagster, MinIO, Polaris, Marquez/OpenLineage, Jaeger.

GitHub Tracking

Milestone:

v0.1.0-alpha.1: https://github.com/Obsidian-Owl/floe/milestone/1

Release-gate issues:

#263 Decouple Dagster Iceberg export from floe-iceberg internals
#278 Release gate: assess contract-layer hard reset before alpha tag
#284 Release gate: triage open tech-debt backlog for alpha cutline
#285 Release gate: run final remote validation lane
#288 Release gate: validate docs and demo walkthrough from Data Engineer and Platform Engineer perspectives
#289 Release gate: prepare v0.1.0-alpha.1 release notes, tag, and rollback posture

Tag rule:

Do not tag v0.1.0-alpha.1 while any issue labeled alpha-blocker is open.
Do not tag v0.1.0-alpha.1 while any issue in the v0.1.0-alpha.1 milestone lacks a release decision.

File Map

Expected modifications during execution:

docs/releases/v0.1.0-alpha.1-checklist.md - update tracking links and final gate evidence.
docs/validation/YYYY-MM-DD-alpha-release-candidate-validation.md - create final release-candidate evidence from the remote contributor validation lane.
docs/validation/YYYY-MM-DD-alpha-docs-demo-walkthrough.md - create persona walkthrough evidence for docs and demo UX.
docs/plans/openchoreo-floe-release-roadmap.md - update only if #278 changes the alpha or post-alpha roadmap.
Source or docs files discovered by #263, #278, #284, #285, or #288 - change in separate issue-specific branches, not in this tracking branch.

Task 1: Resolve #278 Contract-Layer Hard-Reset Release Decision

Files:

Read: docs/superpowers/plans/2026-04-23-contract-layer-hard-reset.md
Read: a local checkout of feat/contract-layer-hard-reset
Update: GitHub issue #278
Step 1: Confirm the feature branch state

Run:

export CONTRACT_RESET_WORKTREE="${CONTRACT_RESET_WORKTREE:-../floe-contract-layer-hard-reset}"
git fetch origin main feat/contract-layer-hard-reset
git -C "$CONTRACT_RESET_WORKTREE" rev-parse --is-inside-work-tree >/dev/null 2>&1 || git worktree add --detach "$CONTRACT_RESET_WORKTREE" origin/feat/contract-layer-hard-reset
git -C "$CONTRACT_RESET_WORKTREE" status --short --branch
test -z "$(git -C "$CONTRACT_RESET_WORKTREE" status --short)" || { echo "Contract reset worktree has local changes; record them in #278 before refreshing."; exit 1; }
git -C "$CONTRACT_RESET_WORKTREE" fetch --all --prune
git -C "$CONTRACT_RESET_WORKTREE" switch --detach origin/feat/contract-layer-hard-reset
git -C "$CONTRACT_RESET_WORKTREE" log --oneline --decorate --max-count=20

Expected: branch feat/contract-layer-hard-reset is clean, refreshed to origin/feat/contract-layer-hard-reset, or any dirty files are listed explicitly in #278 before refreshing.

Step 2: Compare branch contents to current main

Run:

git -C "$CONTRACT_RESET_WORKTREE" diff --stat origin/main...HEAD
git -C "$CONTRACT_RESET_WORKTREE" diff --name-status origin/main...HEAD

Expected: the diff identifies whether the branch contains unreleased user value, superseded work, or release-blocking changes.

Step 3: Record the release decision in #278

Run one of these exact commands after the branch review:

gh issue comment 278 --repo Obsidian-Owl/floe --body "Release decision: non-blocking for v0.1.0-alpha.1. The branch contents have been reviewed against current main and are either superseded or tracked for post-alpha work. Evidence: <summary of files and reason>."
gh issue edit 278 --repo Obsidian-Owl/floe --remove-label alpha-blocker --add-label post-alpha

or:

gh issue comment 278 --repo Obsidian-Owl/floe --body "Release decision: blocking for v0.1.0-alpha.1. The branch contains unreleased value that must be merged or intentionally replaced before the tag. Required action: <specific branch/PR action>."

Expected: #278 clearly states whether the branch blocks the alpha tag.

Step 4: Close or keep #278 according to the decision

Run only if non-blocking:

gh issue close 278 --repo Obsidian-Owl/floe --comment "Release gate resolved: non-blocking for v0.1.0-alpha.1 after branch review. Any remaining value is post-alpha and tracked by linked issues or this issue's history."

Expected: #278 is closed or remains open as a true alpha blocker with a specific next action.

Task 2: Resolve #263 Dagster/Iceberg Alpha Posture

Files:

Read: packages and plugins that import floe_iceberg
Update: GitHub issue #263
Update: docs/releases/v0.1.0-alpha.1-checklist.md if the posture changes
Step 1: Re-check current coupling

Run:

rg -n "floe_iceberg|floe-iceberg|Iceberg" packages plugins tests docs -g '*.py' -g '*.md' -g '*.yaml' -g '*.yml'

Expected: direct Dagster-to-Iceberg imports, if any, are visible and can be assessed against the alpha promise.

Step 2: Confirm alpha product promise

Run:

sed -n '1,220p' docs/releases/v0.1.0-alpha.1-checklist.md
sed -n '1,220p' docs/architecture/opinionation-boundaries.md

Expected: alpha includes Iceberg and OpenLineage/Marquez proof; it does not promise Dagster without Iceberg installed unless the docs say otherwise.

Step 3: Record the release posture in #263

Run if non-blocking for alpha:

gh issue comment 263 --repo Obsidian-Owl/floe --body "Release decision: non-blocking for v0.1.0-alpha.1. The alpha promise includes Iceberg-backed Customer 360 validation and OpenLineage/Marquez proof; Dagster without floe-iceberg installed is not part of the first-alpha compatibility promise. This remains post-alpha architecture debt."
gh issue edit 263 --repo Obsidian-Owl/floe --remove-label alpha-blocker --add-label post-alpha

Run if blocking:

gh issue comment 263 --repo Obsidian-Owl/floe --body "Release decision: blocking for v0.1.0-alpha.1. The current alpha promise requires Dagster to work without floe-iceberg installed, so this coupling must be removed before tagging."

Expected: #263 is either removed from the alpha blocker path or remains open with an explicit code-fix requirement.

Task 3: Triage Open Tech-Debt Backlog (#284)

Files:

Update: GitHub issues #188, #161, #153, #152, #144, #21
Update: GitHub issue #284
Step 1: Review the listed tech-debt issues

Run:

for issue in 188 161 153 152 144 21; do
  gh issue view "$issue" --repo Obsidian-Owl/floe --json number,title,labels,body,url,comments
done

Expected: each issue has enough context to classify alpha relevance.

Step 2: Classify each issue

For every issue, run exactly one of these command pairs.

Alpha-blocking:

gh issue comment <issue-number> --repo Obsidian-Owl/floe --body "Alpha cutline decision: blocking for v0.1.0-alpha.1 because <specific release risk>."
gh issue edit <issue-number> --repo Obsidian-Owl/floe --add-label alpha-blocker --milestone 'v0.1.0-alpha.1'

Post-alpha:

gh issue comment <issue-number> --repo Obsidian-Owl/floe --body "Alpha cutline decision: post-alpha. This is valid technical debt but does not affect first-alpha correctness, security, or demo proof because <specific rationale>."
gh issue edit <issue-number> --repo Obsidian-Owl/floe --add-label post-alpha --remove-label alpha-blocker --remove-milestone

Stale or superseded:

gh issue comment <issue-number> --repo Obsidian-Owl/floe --body "Alpha cutline decision: stale or superseded by <PR/issue/commit>. Closing to keep the release backlog accurate."
gh issue close <issue-number> --repo Obsidian-Owl/floe

Expected: all six listed issues have an explicit cutline comment and correct labels.

Step 3: Close #284 when triage is complete

Run:

gh issue close 284 --repo Obsidian-Owl/floe --comment "Release gate resolved: all open tech-debt issues have been classified as alpha-blocking, post-alpha, stale, or closed."

Expected: #284 is closed unless at least one tech-debt issue remains unclassified.

Task 4: Validate Docs And Demo Walkthrough (#288)

Files:

Create: docs/validation/YYYY-MM-DD-alpha-docs-demo-walkthrough.md
Update: docs pages only when validation finds a concrete defect
Update: docs/releases/v0.1.0-alpha.1-checklist.md
Step 1: Run docs tests and build

Run:

npm --prefix docs-site test
make docs-build
uv run python testing/ci/validate-docs-navigation.py

Expected: all commands pass against current main.

Step 2: Walk the Platform Engineer path

Open and review:

https://obsidian-owl.github.io/floe/platform-engineers/first-platform/
https://obsidian-owl.github.io/floe/platform-engineers/
https://obsidian-owl.github.io/floe/guides/deployment/
https://obsidian-owl.github.io/floe/contributing/

Expected: the path explains Kubernetes portability, identifies DevPod as a contributor/release-validation path rather than a product deployment requirement, and gives a concrete first-platform outcome.

Step 3: Walk the Data Engineer path

Open and review:

https://obsidian-owl.github.io/floe/data-engineers/
https://obsidian-owl.github.io/floe/demo/
https://obsidian-owl.github.io/floe/data-engineers/first-data-product/

Expected: the path explains how a Data Engineer builds a new data product, not only how to inspect the Customer 360 demo.

Step 4: Record validation evidence

Create docs/validation/YYYY-MM-DD-alpha-docs-demo-walkthrough.md with this structure:

# Alpha Docs And Demo Walkthrough - YYYY-MM-DD

## Commit

- Commit: `<git rev-parse HEAD>`
- Docs site: https://obsidian-owl.github.io/floe/

## Automated Checks

| Check | Result | Evidence |
| --- | --- | --- |
| `npm --prefix docs-site test` | PASS/FAIL | paste summary |
| `make docs-build` | PASS/FAIL | paste summary |
| `uv run python testing/ci/validate-docs-navigation.py` | PASS/FAIL | paste summary |

## Platform Engineer Walkthrough

| Page | Result | Notes |
| --- | --- | --- |
| First platform | PASS/FAIL | concrete notes |
| Platform Engineers | PASS/FAIL | concrete notes |
| Deployment guide | PASS/FAIL | concrete notes |
| Contributor remote validation operations | PASS/FAIL | concrete notes |

## Data Engineer Walkthrough

| Page | Result | Notes |
| --- | --- | --- |
| Data Engineers | PASS/FAIL | concrete notes |
| Demo | PASS/FAIL | concrete notes |
| First data product | PASS/FAIL | concrete notes |

## Decision

- Release decision: PASS or BLOCKED
- Blocking follow-up issues: issue links

Expected: the evidence file contains concrete page-level decisions.

Step 5: Close #288 or create follow-up issues

Run if validation passes:

gh issue close 288 --repo Obsidian-Owl/floe --comment "Release gate resolved: docs and demo walkthrough validation passed. Evidence: <validation-file-link>."

Run if validation fails:

gh issue comment 288 --repo Obsidian-Owl/floe --body "Release gate blocked by docs/demo validation findings: <issue links and validation-file-link>."

Expected: #288 is closed only when evidence is linked and no alpha-critical docs/demo defects remain.

Task 5: Run Final Remote Contributor Validation (#285)

Files:

Create: docs/validation/YYYY-MM-DD-alpha-release-candidate-validation.md
Update: docs/releases/v0.1.0-alpha.1-checklist.md
Step 1: Confirm final release-candidate SHA

Run:

git switch main
git pull --ff-only origin main
RELEASE_CANDIDATE_SHA="$(git rev-parse HEAD)"
printf '%s\n' "$RELEASE_CANDIDATE_SHA"
gh run list --repo Obsidian-Owl/floe --branch main --commit "$RELEASE_CANDIDATE_SHA" --limit 10 --json workflowName,status,conclusion,headSha,url,createdAt

Expected: main is clean, the SHA to validate is recorded, and workflow evidence is scoped to that exact SHA.

Step 2: Run the remote validation lane

Run from a stable network connection:

make devpod-test

Expected: remote contributor validation completes and writes a test-artifacts/devpod-run-*/output.log artifact.

Step 3: Run the Customer 360 demo path in DevPod

Run inside the remote validation workspace:

make demo
make demo-customer-360-run
make demo-customer-360-validate
make demo-stop

Expected: demo deploys, run succeeds, validation reports Customer 360 business outputs, storage proof, Dagster proof, Marquez/OpenLineage proof, and Jaeger proof, then cleanup succeeds.

Step 4: Record release-candidate evidence

Create docs/validation/YYYY-MM-DD-alpha-release-candidate-validation.md with this structure:

# Alpha Release Candidate Validation - YYYY-MM-DD

## Release Candidate

- Commit: `<validated main SHA>`
- DevPod provider: configured contributor remote workspace provider
- Workspace source: `<source ref used by DevPod>`

## Gates

| Gate | Result | Evidence |
| --- | --- | --- |
| GitHub Actions CI | PASS/FAIL | URL |
| GitHub Actions Helm CI | PASS/FAIL | URL |
| GitHub Actions Docs | PASS/FAIL | URL |
| Security scans | PASS/FAIL | URLs |
| `make devpod-test` | PASS/FAIL | artifact path and summary |
| `make demo` | PASS/FAIL | command output summary |
| `make demo-customer-360-run` | PASS/FAIL | Dagster run ID |
| `make demo-customer-360-validate` | PASS/FAIL | validator summary |
| `make demo-stop` | PASS/FAIL | cleanup summary |

## Service Evidence

| Service | Evidence |
| --- | --- |
| Dagster | run ID and success evidence |
| MinIO | Customer 360 object evidence |
| Polaris | table/catalog evidence |
| Marquez | job/dataset lineage evidence |
| Jaeger | trace evidence |

## Decision

- Release decision: PASS or BLOCKED
- Blocking follow-up issues: issue links

Expected: the evidence file is self-contained enough to justify or block the tag.

Step 5: Close #285 only after evidence passes

Run:

gh issue close 285 --repo Obsidian-Owl/floe --comment "Release gate resolved: final remote contributor validation passed on commit <sha>. Evidence: <validation-file-link>."

Expected: #285 is closed only when the validation file proves the gate.

Task 6: Prepare Release Notes And Tag (#289)

Files:

Update: docs/releases/v0.1.0-alpha.1-checklist.md
Create or update: release notes draft if the repository adds one before tag
Update: GitHub issue #289
Step 1: Confirm no blockers remain

Run:

gh issue list --repo Obsidian-Owl/floe --state open --label alpha-blocker --json number,title,url
gh issue list --repo Obsidian-Owl/floe --state open --milestone 'v0.1.0-alpha.1' --json number,title,labels,url

Expected: both commands return empty arrays or only explicitly non-blocking issues that have a recorded release decision and no alpha-blocker label.

Step 2: Confirm release checklist is current

Run:

sed -n '1,260p' docs/releases/v0.1.0-alpha.1-checklist.md

Expected: every required gate has current evidence from the final release-candidate commit.

Step 3: Draft release notes

Include these sections in the GitHub release draft:

# v0.1.0-alpha.1

## What This Alpha Proves

- Floe can deploy the Customer 360 demo platform through the validated Kubernetes lane.
- The demo produces business outputs and validates storage, orchestration, lineage, and tracing evidence.
- The docs site is published and has persona-specific onboarding for Platform Engineers and Data Engineers.

## Known Alpha Limits

- The alpha validates the Iceberg-backed Customer 360 path; Dagster without floe-iceberg installed is post-alpha architecture debt unless #263 was resolved differently.
- DevPod remote contributor validation is the validated release lane; other Kubernetes providers are intended but not yet proven as alpha gates.
- Any post-alpha issues listed in the release checklist remain outside the first-alpha promise.

## Evidence

- Release checklist: `docs/releases/v0.1.0-alpha.1-checklist.md`
- Final validation: `<validation evidence link>`
- Docs/demo walkthrough: `<walkthrough evidence link>`

Expected: release notes honestly describe proven behavior and known limits.

Step 4: Record tag and rollback commands

Add this command block to #289 before tagging:

export RELEASE_CANDIDATE_SHA="<sha validated in #285>"
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "$RELEASE_CANDIDATE_SHA" || { echo "main moved since validation; rerun #285 before tagging."; exit 1; }
git tag -a v0.1.0-alpha.1 "$RELEASE_CANDIDATE_SHA" -m "v0.1.0-alpha.1"
git push origin v0.1.0-alpha.1

# Rollback if the tag is bad and no consumers should use it:
git tag -d v0.1.0-alpha.1
git push origin :refs/tags/v0.1.0-alpha.1

Expected: the release owner can tag or roll back without guessing.

Step 5: Close #289

Run after the tag is created and release notes are published:

gh issue close 289 --repo Obsidian-Owl/floe --comment "Release gate resolved: v0.1.0-alpha.1 tag and release notes published with evidence links."

Expected: #289 is the final alpha tracking issue closed.

Self-Review

Spec coverage: covers release-review decisions (#263, #278), tech-debt triage (#284), final remote contributor validation (#285), docs/demo validation (#288), and final release/tag readiness (#289).
Placeholder scan: the plan contains no deferred work markers; angle-bracket substitutions are explicit command arguments to replace at execution time with concrete issue links, commit SHAs, and validation file links.
Type consistency: issue numbers, release tag, milestone name, and evidence paths are consistent across tasks.