Generate PR pending-work markdown log from backlog issue sections #360

New issue

Closed

opened 2026-06-10 20:42:34 +00:00 by steve · 0 comments

steve commented

2026-06-10 20:42:34 +00:00

Owner

Add a tracked markdown handoff file to PR-based backlog work so reviewers can see remaining and partial work directly in the branch, not only in chat.

Problem

backlog:start/backlog:submit currently track branch and PR metadata in the issue file and PR body, but they do not create a dedicated markdown artifact in the branch that summarizes pending or partially completed work for reviewers.

Goal

Generate and maintain a tracked markdown file for PR workflow issues that captures the current pending or partial work log from the issue body.

Scope

Add a generated markdown file under .issues/ for PR workflow issues.
Seed and refresh the file from the issue's backlog sections.
Document where the file lives and how maintainers should update the source sections.
Cover the behavior with script unit tests.

Non-goals

Replacing the issue file as the canonical source of truth.
Adding Forgejo-specific PR comments or attachments.
Building a general rendered task-reporting site.

Acceptance Criteria

backlog:start creates a tracked markdown file for the active issue inside .issues/.
The markdown file summarizes pending or partially completed work using durable sections from the issue body.
The workflow refreshes the file when PR metadata changes so it stays useful during handoff.
The backlog spec explains the file path, purpose, and source sections.
Script tests cover the generated content and lifecycle.

Implementation Notes

Use the issue markdown body as canonical input rather than introducing a second editable source.
Prefer a deterministic per-issue path so the file remains stable across updates.
If the existing issue helper regression blocks normal backlog commands during implementation, fix the regression as part of the same change set rather than working around it permanently.

Suggested Files or Specs To Inspect

spec/src/80-maintenance/issues-backlog.md
spec/src/80-maintenance/agent-task-state.md
scripts/backlog-workflow-lib.mjs
scripts/backlog-workflow.test.mjs
scripts/issue-sync.mjs

Validation Commands

node --test scripts/backlog-workflow.test.mjs
node --test scripts/issue-sync-lib.test.mjs
pnpm check:all

Follow-up to #359

Follow-up Tasks

If reviewers want richer context later, consider linking the generated file from the PR body with a Forgejo branch-relative URL.

Branch

Base ref:
Base revision:
Work branch / JJ bookmark:
Work change:

Pull Request

PR:
State:
Head SHA:
CI:

Regression Notes

Last known good:
Suspect change:
Validation command that catches this class of bug:

Implementation Summary

backlog:start/submit/pr-status now generate and refresh .issues/pr/.md from Implementation Notes, Follow-up Tasks, Problem, Goal, and Validation Commands. Fixed workflow frontmatter churn by not treating default work_base_ref alone as active PR metadata. Spec and tests updated.

Add a tracked markdown handoff file to PR-based backlog work so reviewers can see remaining and partial work directly in the branch, not only in chat. ## Problem `backlog:start`/`backlog:submit` currently track branch and PR metadata in the issue file and PR body, but they do not create a dedicated markdown artifact in the branch that summarizes pending or partially completed work for reviewers. ## Goal Generate and maintain a tracked markdown file for PR workflow issues that captures the current pending or partial work log from the issue body. ## Scope - Add a generated markdown file under `.issues/` for PR workflow issues. - Seed and refresh the file from the issue's backlog sections. - Document where the file lives and how maintainers should update the source sections. - Cover the behavior with script unit tests. ## Non-goals - Replacing the issue file as the canonical source of truth. - Adding Forgejo-specific PR comments or attachments. - Building a general rendered task-reporting site. ## Acceptance Criteria - `backlog:start` creates a tracked markdown file for the active issue inside `.issues/`. - The markdown file summarizes pending or partially completed work using durable sections from the issue body. - The workflow refreshes the file when PR metadata changes so it stays useful during handoff. - The backlog spec explains the file path, purpose, and source sections. - Script tests cover the generated content and lifecycle. ## Implementation Notes - Use the issue markdown body as canonical input rather than introducing a second editable source. - Prefer a deterministic per-issue path so the file remains stable across updates. - If the existing issue helper regression blocks normal backlog commands during implementation, fix the regression as part of the same change set rather than working around it permanently. ## Suggested Files or Specs To Inspect - `spec/src/80-maintenance/issues-backlog.md` - `spec/src/80-maintenance/agent-task-state.md` - `scripts/backlog-workflow-lib.mjs` - `scripts/backlog-workflow.test.mjs` - `scripts/issue-sync.mjs` ## Validation Commands - `node --test scripts/backlog-workflow.test.mjs` - `node --test scripts/issue-sync-lib.test.mjs` - `pnpm check:all` ## Related Issues - Follow-up to #359 ## Follow-up Tasks - If reviewers want richer context later, consider linking the generated file from the PR body with a Forgejo branch-relative URL. ## Branch - Base ref: - Base revision: - Work branch / JJ bookmark: - Work change: ## Pull Request - PR: - State: - Head SHA: - CI: ## Regression Notes - Last known good: - Suspect change: - Validation command that catches this class of bug: ## Implementation Summary backlog:start/submit/pr-status now generate and refresh .issues/pr/<issue>.md from Implementation Notes, Follow-up Tasks, Problem, Goal, and Validation Commands. Fixed workflow frontmatter churn by not treating default work_base_ref alone as active PR metadata. Spec and tests updated.

steve

2026-06-10 20:42:34 +00:00