docs: man-page command reference (HowToRun.md); short-form flags in README - #11
Conversation
…EADME PRs #8 and #10 shipped flags the docs never caught up with (--keep-line-breaks, --sync-bodies, --force). docs/HowToRun.md is now the complete option-by-option account, man-page shaped per tool (SYNOPSIS / DESCRIPTION / OPTIONS / EXIT STATUS / EXAMPLES): populate with all fourteen options including the --sync-bodies classification table (in-sync / reflow / divergent) and the update-artifact in-sync rules; update with its diff(1) exit codes and the make-collapses-to-2 caveat; lint. It also shows the interchangeable invocation forms per engine channel (make / installed CLI / nix run / plain python), and — the requested nicety — how to use _utils.text_unwrap directly on any markdown file, both as a heredoc one-liner and as a tiny PATH script; both examples were executed verbatim before landing. The README stays lean: a short-form flag list per tool plus the link, keeping the landing page clean while every option is still findable from it. AI-assisted: Claude Fable 5 (Anthropic)
There was a problem hiding this comment.
Pull request overview
Adds comprehensive command documentation for the roadmap engine.
Changes:
- Documents populate, update, and lint options, behavior, and exit codes.
- Adds examples for directly unwrapping Markdown.
- Adds a concise README command reference.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
README.md |
Adds short-form flag reference and documentation link. |
docs/HowToRun.md |
Adds detailed command and Markdown-unwrapping reference. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| with `--sync-bodies`. `--issues-only` requires the plan's milestones | ||
| to already exist on GitHub: issues whose declared milestone is | ||
| missing are skipped and counted as failures rather than created | ||
| milestone-less (populate never revisits existing issues, so that | ||
| incompleteness would be permanent). |
There was a problem hiding this comment.
Confirmed — and the inaccuracy predates this page: populate's own module docstring has carried the milestone-only claim since PR #1. Both fixed in ed5f2e1: the OPTIONS entry now states that --issues-only creates neither milestones nor labels, so an issue whose declared milestone OR any referenced label is unavailable is not created and counts as a failure (with the permanence rationale — populate never revisits existing issues); the module docstring says the same in short form.
| 0 everything requested was created / synced or already existed | ||
| 1 some items failed, were refused (label collisions, divergent | ||
| bodies), or were skipped |
There was a problem hiding this comment.
Confirmed — --start-from filtering and already-existing items exit 0, and the unqualified 'were skipped' invited exactly the misreading you describe (the confusion is understandable: the executor's own per-item output says 'skipped —' for BLOCKED issues, which do count toward exit 1). Fixed in ed5f2e1: exit 1 is now enumerated precisely (creation errors, issues blocked by an unavailable label or milestone, label near-collisions, divergent bodies under --sync-bodies), and exit 0 explicitly covers deliberate filtering.
| The unwrap logic populate uses lives in the engine's `_utils` package | ||
| (`scripts/_utils/text_unwrap.py`) as a pure function — structure-aware | ||
| (headings, tables, fenced/indented code, blockquotes, list items, | ||
| region markers, and the plan grammar's `**Labels:**`-style metadata | ||
| all survive byte-for-byte), sentence-spacing-preserving, and | ||
| idempotent. To use it directly on a file, from an engine checkout: |
There was a problem hiding this comment.
Confirmed — 'list items survive byte-for-byte' overclaimed, and the reflow of item continuations is half the feature, not an exception to it. Fixed in ed5f2e1: the section now separates the two guarantees — list STRUCTURE is preserved (markers, one item per line, empty items untouched) while wrapped prose INSIDE an item reflows onto its marker line exactly like any paragraph — matching what the golden cases in test_text_unwrap.py pin.
All three findings were legitimate documentation inaccuracies: - --issues-only requires referenced LABELS to exist, not only milestones — the mode creates neither, and issue_blocker counts an issue with an unavailable label as a failure. Fixed in HowToRun and in populate's own module docstring, which carried the same milestone-only claim since PR #1. - Exit status 1's unqualified 'were skipped' invited misreading: --start-from filtering and already-existing items exit 0; only blocked issues (unavailable label/milestone), creation errors, collisions, and sync refusals reach exit 1. The wording now says exactly that, and exit 0 explicitly covers deliberate filtering. - 'List items survive byte-for-byte' overclaimed: list STRUCTURE is preserved (markers, one item per line, empty items untouched) while wrapped prose INSIDE an item is deliberately reflowed — half the feature. The unwrap section now draws that line. AI-assisted: Claude Fable 5 (Anthropic)
Documentation catch-up for the features PRs #8 and #10 shipped (
--keep-line-breaks,--sync-bodies,--force), plus the full option inventory that was never written down.docs/HowToRun.md— man-page-style reference per tool (SYNOPSIS / DESCRIPTION / OPTIONS / EXIT STATUS / EXAMPLES): all fourteen populate options with the--sync-bodiesclassification table (in-sync / reflow / divergent, the update-artifact in-sync rules, per-item refusal semantics); update's diff(1) exit codes with the make-collapses-to-2 caveat; lint. Opens with the four interchangeable invocation forms (make target, installed CLI,nix runapp, plain python)._utils.text_unwrapdirectly — a copy-paste heredoc one-liner and a tiny reusable PATH script. Both examples were executed verbatim against a probe file before landing (including an idempotence check).No engine code changes; suite still 168/168 and
make lintclean.AI-assisted development: Claude Fable 5 (Anthropic)