Fix backlog helper argument parsing and duplicate mirror diagnostics #182

New issue

Closed

opened 2026-05-31 19:27:10 +00:00 by steve · 0 comments

steve commented

2026-05-31 19:27:10 +00:00

Owner

Problem

Backlog helper commands have three workflow bugs that made the Full Registry V1
backlog setup harder than it should have been:

pnpm backlog:new -- "Title" is documented, but the CLI parser treats bare
-- as an option name and loses the title.
backlog:doctor can exit with status 1 while printing all OK checks when
the local mirror has the same issue number in both .issues/open/ and
.issues/closed/.
backlog:sync can leave stale same-number files in the opposite state
directory, so local mirror state can disagree with Forgejo.

Goal

Make the documented backlog commands reliable, make doctor output match its exit
status, and make pull/sync clean stale local issue files for the same Forgejo
issue number.

Scope

Ignore the package-manager bare -- delimiter in backlog CLI argument parsing
so subsequent script options still parse normally.
Add explicit duplicate issue number diagnostics.
Remove stale same-number local issue files when pulling remote issue state.
Keep sync and doctor duplicate reporting consistent.
Update backlog docs and skill guidance.
Add focused script tests for parser behavior, duplicate number reporting, and
stale mirror cleanup selection.

Non-goals

Do not manually repair unrelated issue content beyond the stale mirror behavior
owned by the sync tool.
Do not change Forgejo issue state semantics or issue dependency behavior.

Acceptance Criteria

pnpm backlog:new -- "Parser smoke issue" --subsystem backlog --dry-run keeps
Parser smoke issue as the title.
close -- 173 --summary "..." and reopen -- 173 --reason "..." parse the
issue number as positional input.
Same-number open/closed local mirror conflicts are reported explicitly by
doctor.
Doctor exits 0 when it prints no failures.
Pull/sync removes stale same-number local files in the opposite state
directory or stale slug path.
Script tests cover the parser and mirror-diagnostic edge cases.

Implementation Notes

Prefer fixing the parser instead of changing documented command usage.
Use a shared duplicate/conflict model so sync and doctor agree.
The current local #160 open/closed duplicate is the regression shape this
work must handle.

Suggested Files or Specs To Inspect

scripts/issue-sync.mjs
scripts/issue-sync-lib.mjs
scripts/issue-sync-lib.test.mjs
spec/src/80-maintenance/issues-backlog.md
.agents/skills/issue-backlog/SKILL.md

Validation Commands

node --test scripts/issue-sync-lib.test.mjs scripts/issue-sync-progress.test.mjs
pnpm test:scripts
make spec-lint
pnpm backlog:new -- "Parser smoke issue" --subsystem backlog --dry-run
pnpm backlog:doctor --quiet
pnpm backlog:doctor --strict --quiet
pnpm backlog:sync --dry-run --quiet

Follow-up Tasks

Implementation Summary

Fixed backlog helper argument parsing for pnpm-style bare -- commands, added same-number mirror conflict diagnostics, cleaned stale opposite-state mirrors during sync/pull writes, aligned duplicate summaries, and documented the behavior.

## Problem Backlog helper commands have three workflow bugs that made the Full Registry V1 backlog setup harder than it should have been: - `pnpm backlog:new -- "Title"` is documented, but the CLI parser treats bare `--` as an option name and loses the title. - `backlog:doctor` can exit with status `1` while printing all OK checks when the local mirror has the same issue number in both `.issues/open/` and `.issues/closed/`. - `backlog:sync` can leave stale same-number files in the opposite state directory, so local mirror state can disagree with Forgejo. ## Goal Make the documented backlog commands reliable, make doctor output match its exit status, and make pull/sync clean stale local issue files for the same Forgejo issue number. ## Scope - Ignore the package-manager bare `--` delimiter in backlog CLI argument parsing so subsequent script options still parse normally. - Add explicit duplicate issue number diagnostics. - Remove stale same-number local issue files when pulling remote issue state. - Keep sync and doctor duplicate reporting consistent. - Update backlog docs and skill guidance. - Add focused script tests for parser behavior, duplicate number reporting, and stale mirror cleanup selection. ## Non-goals - Do not manually repair unrelated issue content beyond the stale mirror behavior owned by the sync tool. - Do not change Forgejo issue state semantics or issue dependency behavior. ## Acceptance Criteria - `pnpm backlog:new -- "Parser smoke issue" --subsystem backlog --dry-run` keeps `Parser smoke issue` as the title. - `close -- 173 --summary "..."` and `reopen -- 173 --reason "..."` parse the issue number as positional input. - Same-number open/closed local mirror conflicts are reported explicitly by doctor. - Doctor exits `0` when it prints no failures. - Pull/sync removes stale same-number local files in the opposite state directory or stale slug path. - Script tests cover the parser and mirror-diagnostic edge cases. ## Implementation Notes - Prefer fixing the parser instead of changing documented command usage. - Use a shared duplicate/conflict model so `sync` and `doctor` agree. - The current local `#160` open/closed duplicate is the regression shape this work must handle. ## Suggested Files or Specs To Inspect - `scripts/issue-sync.mjs` - `scripts/issue-sync-lib.mjs` - `scripts/issue-sync-lib.test.mjs` - `spec/src/80-maintenance/issues-backlog.md` - `.agents/skills/issue-backlog/SKILL.md` ## Validation Commands - `node --test scripts/issue-sync-lib.test.mjs scripts/issue-sync-progress.test.mjs` - `pnpm test:scripts` - `make spec-lint` - `pnpm backlog:new -- "Parser smoke issue" --subsystem backlog --dry-run` - `pnpm backlog:doctor --quiet` - `pnpm backlog:doctor --strict --quiet` - `pnpm backlog:sync --dry-run --quiet` ## Related Issues ## Follow-up Tasks ## Implementation Summary Fixed backlog helper argument parsing for pnpm-style bare -- commands, added same-number mirror conflict diagnostics, cleaned stale opposite-state mirrors during sync/pull writes, aligned duplicate summaries, and documented the behavior.

steve added this to the Full Registry V1 milestone

2026-05-31 19:27:10 +00:00

steve

2026-05-31 19:27:10 +00:00