feat(opencode): file unresolved bugs/blockers as TODO sub-issues in Phase 9

A workflow run wrapped up with "Unresolved: Score not resetting on game
restart (pre-existing bug, out of scope)" — a real bug discovered while
implementing GAL-39. Buried in summary.md, which is per-run, untracked,
overwritten on the next run, and read by nobody (the user has walked
away by design).

Adds a File Follow-ups subsection to Phase 9, after the TODO Update.
Tracked-worthy items are routed through @pm as sub-issues of the
current issue (parent: $ISSUE_ID), so they auto-show in the parent's
Sub-issues list and don't need a README.md category at unattended
runtime. Three categories file an issue:

- Pre-existing bugs found out of scope → label `bug`
- Unresolved review-loop blockers (Phase 4 or 8 cycle exhaustion)
  → label `followup`
- @test NOT_TESTABLE "future seam" notes → label `tech-debt`

Things explicitly NOT filed: @simplify advisories the orchestrator
chose not to act on (records, not missing work), cosmetic nits,
duplicates of existing issues. Those live in the run summary's new
"Advisory notes (not filed)" section.

Renames "Commit TODO Changes" subsection so the worked issue update
plus any filed follow-ups commit together as one atomic chore(todo)
commit. The Run Summary's old "Unresolved items" bullet is replaced
with two sharper bullets: "Filed follow-ups" (lists IDs of created
sub-issues) and "Advisory notes (not filed)".
This commit is contained in:
Harald Hoyer 2026-05-08 06:29:46 +02:00
parent c3407c9c98
commit aac4d44a49

View file

@ -459,17 +459,44 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
- Add a comment of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA><one-line summary>` (date from the shell, never fabricated).
- Propagate any status flip to the dependent index: `TODO/README.md` for top-level issues (`parent: null`), or the parent file's `## Sub-issues` line for sub-issues.
- If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off (flip `- [ ]` to `- [x]` under `## Acceptance criteria`).
- Commit the TODO/ changes as a separate atomic commit: `chore(todo): update <issue-id> status and progress`. Stage the issue file plus any propagated index file (README.md or parent file).
### File Follow-ups
Tracked-worthy unresolved items must become real TODO issues; otherwise they vanish into the per-run `summary.md` and the user (who has walked away) never sees them. Before writing the summary, scan the run for items in these categories and dispatch `@pm` to file each as a **sub-issue of the current issue** (`parent: $ISSUE_ID`).
| Source | New issue label | Title style |
|---|---|---|
| Pre-existing bug discovered while working but out of scope (e.g. "Score not resetting on game restart" found during GAL-39) | `bug` | Imperative fix description ("Reset score on game restart") |
| Unresolved blocker after a review loop exhausted its cycle limit (Phase 4 plan review or Phase 8 final review) | `followup` | Reference the `@check` finding |
| `@test` `NOT_TESTABLE` "future seam" notes that imply a real test gap | `tech-debt` | Describe the missing seam |
**Do NOT file follow-ups for:**
- `@simplify` advisory recommendations the orchestrator chose not to act on — these are records, not missing work; they belong in the run summary.
- Cosmetic / formatting / naming nits.
- Anything already covered by an existing TODO issue (`@pm` lists existing issues; check the title/description before filing a duplicate).
**Routing rules:**
- Each new issue is a sub-issue (`parent: $ISSUE_ID`). `@pm` will add it to the parent's `## Sub-issues` list automatically. The user can promote it to top-level later if it deserves its own slot.
- Issue body must include a "Discovered during" paragraph naming the run's branch and (where relevant) commit SHA, plus enough context for the user to triage it later without having to re-read the run.
- Status: `Todo`. Default labels per the table; the orchestrator may add additional labels inferred from the parent (e.g. propagate `gameplay` from GAL-39 to a gameplay-relevant follow-up).
- The Run Summary (next subsection) lists each filed follow-up by ID so the user has one place to see them.
### Commit TODO Changes
After both the TODO Update and File Follow-ups steps, commit everything under `TODO/` in a single atomic commit: `chore(todo): update <issue-id> status, file follow-ups`. Stage the worked issue file, the dependent index (README.md or parent file), and any newly created follow-up issue files.
If no follow-ups were filed, the commit message simplifies to `chore(todo): update <issue-id> status and progress` and only the TODO Update changes are staged.
### Run Summary
- Write `$RUN_DIR/summary.md` with:
- **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-07T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one.
- **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-08T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one.
- Issue reference and title
- Branch name and final commit SHA(s)
- Summary of implementation
- TDD evidence (RED→GREEN per task, NOT_TESTABLE justifications)
- Review outcomes (plan review + final review verdicts)
- Unresolved items (if any)
- **Filed follow-ups** — list each new issue created in the File Follow-ups step by ID, title, and reason (`bug` / `followup` / `tech-debt`). If none, write "None."
- **Advisory notes (not filed)** — any `@simplify` or `@check` recommendations the orchestrator chose not to act on and did not turn into a TODO. These are records for the user to consider, not tracked work.
- Files changed
- **Do not commit anything under `.workflow/`.** The whole directory is per-run, per-branch state. Recommend the user add `.workflow/` to `.gitignore` if not already.