# GSD Public Repo Autonomous Execution Design

> Historical design record retained for context. This document captures a prior planning decision and is not a live repository instruction document.

> `.planning/*` note: these references point to local historical planning artifacts from the original workflow, not public repo files that this spec expects readers to create or edit today.

## Quick Links

- [Superpowers Docs Index](../README.md)
- [Related rollout plan](../plans/2026-04-18-gsd-public-repo-autonomous-rollout.md)
- [Goal](#goal)
- [Problem](#problem)
- [Scope](#scope)
- [Approaches Considered](#approaches-considered)
- [Recommended Approach](#recommended-approach)
- [Design](#design)
- [Files Affected](#files-affected)
- [Testing and Verification](#testing-and-verification)
- [Open Decisions Already Resolved](#open-decisions-already-resolved)

## Goal

Make the existing milestone planning artifacts explicitly safe for autonomous execution in a public repo by embedding human-authored commit/release rules everywhere GSD execution will read them, and by extending milestone closeout so Phase 8 finishes with versioning and the repo release workflow.

## Problem

The current planning state is internally consistent for audit remediation, but it still carries planning-era assumptions that are wrong for an autonomous public-repo run:

- `.planning/PROJECT.md` and `.planning/REQUIREMENTS.md` still describe release, publish, and push work as out of scope.
- `.planning/ROADMAP.md` stops Phase 8 at the manifest-wiring refactor and does not define release closeout.
- `.planning/config.json` has workflow toggles, but no repo-local policy describing how commits and release text must read in a public repository.
- Existing per-plan files do not carry an in-band execution rule that forbids AI-slop commit messages or requires final version/release work.

That leaves too much to implied behavior. In a public repo, implied behavior is how you end up with garbage commit text and a "done" milestone that never actually ships.

## Scope

This design only covers planning and execution-policy artifacts for the current `clickup-cli` milestone.

In scope:

- Add one canonical public-repo execution policy for this repo.
- Propagate that policy into the top-level `.planning` docs that drive GSD autonomous execution.
- Patch the existing phase plan files so executor agents see the public-repo rules directly in-band.
- Extend the Phase 8 closeout to include version bump and release workflow execution.

Out of scope:

- Changing the actual GSD framework installed outside this repo.
- Reworking the milestone's audit-finding decomposition.
- Executing the implementation or release immediately in this design step.

## Approaches Considered

### Approach 1: Shared Policy Plus Full Propagation

Create one canonical public-repo policy file, reference it from top-level planning docs, and patch every existing `*-PLAN.md` so the same rules appear directly where execution agents operate.

Pros:

- One source of truth for future updates.
- Current plan files become self-contained for autonomous execution.
- Makes the release/version closeout explicit instead of implied.

Cons:

- Largest documentation diff.
- Some repetition across existing plan files.

### Approach 2: Pure Inline Rewrites

Patch every planning artifact directly without introducing a shared policy document.

Pros:

- No indirection.
- Every rule is immediately visible in the edited file.

Cons:

- Easy to drift later.
- Harder to review and maintain.

### Approach 3: Config/Workflow Only

Try to solve the behavior by editing only `.planning/config.json` and a few top-level files.

Pros:

- Smallest diff.

Cons:

- Too implicit for a public repo.
- Leaves existing plan files blind to the policy during execution.
- Does not make release closeout concrete enough.

## Recommended Approach

Use Approach 1.

This is the smallest design that is still trustworthy. A public repo wants explicit rules, not wishful thinking hidden in a config toggle.

## Design

### 1. Canonical Public Repo Rules

Add `.planning/PUBLIC-REPO-RULES.md` as the canonical execution-policy document for this milestone.

It should define:

- this repository is public and all autonomous work must assume public visibility
- commit messages must read like normal human developer commits
- commit messages must not mention AI, agents, Claude, GSD, or generated-by phrasing
- the same human-authored standard applies to release notes, changelog prose, and GitHub release text
- wave-level and phase-level commits follow the same rule as any other commit
- milestone completion is not considered done until the Phase 8 closeout release workflow finishes

The wording should be direct and operational rather than aspirational. Executor agents need rules they can follow, not philosophy.

### 2. Top-Level Planning Updates

Update the repo's primary `.planning` control documents so they no longer contradict the desired autonomous behavior.

#### `.planning/PROJECT.md`

- Move release/version work out of out-of-scope language.
- Add the repo-public execution constraint to the Constraints section.
- Reference `.planning/PUBLIC-REPO-RULES.md` from Context or Constraints.
- Clarify that milestone closeout includes final version/release work after implementation phases complete.

#### `.planning/REQUIREMENTS.md`

- Remove or rewrite the current out-of-scope statement that excludes release/publish/push work.
- Add a release-closeout requirement covering version bump, changelog update, validation, build, tag, publish, push, and GitHub release creation.
- Keep the existing finding traceability intact; the release requirement can sit alongside the milestone requirements as closeout work rather than pretending it came from an audit finding.

#### `.planning/ROADMAP.md`

- Update the overview to mention public-repo-safe execution and human-authored git history.
- Extend Phase 8 so it explicitly includes milestone closeout.
- Add a new plan entry under Phase 8 for release/version closeout, rather than overloading `08-02-PLAN.md`.
- Preserve the current audit-finding decomposition; the release plan is a terminal closeout plan layered after the F-601 refactor plans.

#### `.planning/STATE.md`

- Add a clear note that autonomous execution for this milestone must follow `.planning/PUBLIC-REPO-RULES.md`.
- Make the terminal state explicit: after implementation phases, the workflow still owes version and release closeout.

#### `.planning/config.json`

- Keep changes minimal.
- Only update it if a repo-local note is needed to reflect that autonomous execution now includes milestone closeout behavior. Do not try to encode prose policy into config where markdown documents already do the job better.

### 3. In-Band Propagation Into Existing Plans

Patch all existing `.planning/phases/**/**-PLAN.md` files with a short, consistent execution block near the top of each plan.

That block should tell executor agents:

- this repo is public
- commit text must be human-authored and repo-normal
- never mention AI, agent names, Claude, or GSD in commit text
- keep commit summaries focused on the code change itself
- if the plan belongs to the final phase closeout path, release/version rules also apply

This duplication is intentional. Autonomous execution should not depend on the agent remembering to cross-reference one top-level note while working through a plan in isolation.

### 4. Phase 8 Closeout Design

Add `.planning/phases/08-unified-command-manifest/08-03-PLAN.md` as a dedicated release closeout plan.

This plan should remain narrowly scoped to shipping work after the implementation plans are done. It should not be jammed into `08-02-PLAN.md`, because wiring refactor verification and release execution are different rollback boundaries.

The new plan should describe:

- version bump locations: `src/clickup_cli/__init__.py` and `tests/test_cli.py`
- changelog update rules based on the existing `CHANGELOG.md` format
- required validation commands from the repo's `release` skill:
  - `ruff check src/ tests/`
  - `pytest -v`
  - `clickup --help`
  - `bash scripts/validate-cli-output.sh`
- build steps and artifact validation
- git tag creation and push
- PyPI publish
- GitHub release creation with attached artifacts

This plan should also carry the same public-repo language rules for commit and release text.

### 5. Data Flow

The updated execution flow should look like this:

1. GSD autonomous reads top-level milestone docs.
2. Top-level docs point to `.planning/PUBLIC-REPO-RULES.md` and no longer contradict release execution.
3. Executor agents read each phase plan and also see the same public-repo rules inline.
4. Phases 1 through 7 execute normally under the new commit-message constraints.
5. Phase 8 executes manifest work, then runs the explicit closeout plan for version/release.
6. Milestone completion only happens after release closeout finishes.

### 6. Error Handling and Failure Mode Expectations

If release validation fails at the end:

- the milestone remains incomplete
- `.planning/STATE.md` should still reflect that release closeout is pending
- the failure should be treated as a milestone blocker, not as optional cleanup

If a plan file drifts from the canonical public-repo policy later:

- the canonical policy remains the source of truth
- the duplicated in-band rule blocks should be updated to match during future planning maintenance

If the release workflow needs user credentials or confirmation at publish time:

- the plan should still encode the full release workflow
- any explicit user-confirmation gate should be called out as part of the release closeout plan rather than omitted from the plan entirely

## Files Affected

Expected new files:

- `.planning/PUBLIC-REPO-RULES.md`
- `.planning/phases/08-unified-command-manifest/08-03-PLAN.md`

Expected modified files:

- `.planning/PROJECT.md`
- `.planning/REQUIREMENTS.md`
- `.planning/ROADMAP.md`
- `.planning/STATE.md`
- all existing `.planning/phases/**/**-PLAN.md`

## Testing and Verification

This design change is documentation-driven, so verification is structural rather than behavioral.

Verification should confirm:

- the new canonical policy file exists
- top-level planning docs no longer describe release work as out of scope
- Phase 8 explicitly includes a dedicated release/version closeout plan
- every existing plan file contains the in-band public-repo execution rules block
- the resulting docs are internally consistent about milestone completion and public-repo commit/release language

## Open Decisions Already Resolved

- Release boundary: full release flow at the end of Phase 8
- Propagation scope: update top-level docs and patch existing plan files everywhere

## Notes

This design intentionally changes planning artifacts before autonomous execution begins. That is the point. If the repo is public, the workflow rules need to be boringly explicit before the first autonomous wave writes a single commit.
