diff --git a/src/content/docs/dn/completing-github-issues.md b/src/content/docs/dn/completing-github-issues.md index b85d32a..1e65e0d 100644 --- a/src/content/docs/dn/completing-github-issues.md +++ b/src/content/docs/dn/completing-github-issues.md @@ -81,13 +81,15 @@ the branch and pull request provide enough isolation for review. ## Complete and verify work locally Run `kickstart` without a publish mode to keep the plan and changes in the -current workspace: +current workspace. Attended kickstart exits after success — it does not close +the GitHub issue or ask whether to continue: ```bash dn kickstart 123 dn until validate .github/dn/gambit.json dn until run .github/dn/gambit.json dn land --issue-testplan +dn todo done 123 ``` Configure the gambit so its generator resolves problems in the current issue @@ -116,9 +118,12 @@ generator and verifier within the configured budget, leaving all work local. Review the resulting diff before running `land`. `land` validates the completed plan, groups the workspace changes into local -commits, and removes the plan. `--issue-testplan` also upserts a concise -`## Test Plan` checklist on the linked issue. It does not push or open a pull -request. +commits, and removes the plan. It targets **one plan at a time** (explicit path, +`PLAN`, or newest `plans/*.plan.md`). Do not stack multiple local kickstarts +before landing — use `--publish pr|direct` when you want each issue published +without a separate land step. `--issue-testplan` also upserts a concise +`## Test Plan` checklist on the linked issue. It does not push, open a pull +request, or close the issue. Push the resulting feature branch or bookmark with your usual VCS workflow, then open the pull request: @@ -240,8 +245,10 @@ dn kickstart --publish pr --milestone 42 --complete `dn init stack` scores and orders the open issues. `--once` processes the next unchecked item and is suitable for CI. `--complete` processes every remaining -item. Use `--publish pr` in an ephemeral runner so each completed issue produces -a durable pull request. +item and **requires** `--publish pr` or `--publish direct` so each stack item is +published before the next. Use `--publish pr` in an ephemeral runner so each +completed issue produces a durable pull request. On `--once` / `--complete` +success, the stack item is marked done and the GitHub issue is closed. To clarify the milestone outcome before creating its execution queue, run: diff --git a/src/content/docs/dn/filesystem-context.md b/src/content/docs/dn/filesystem-context.md index 3cd8491..1743fc1 100644 --- a/src/content/docs/dn/filesystem-context.md +++ b/src/content/docs/dn/filesystem-context.md @@ -127,8 +127,9 @@ This produces: - `plans/{owner}_{repo}_{milestone}.stack.json` — machine-readable queue state Commit both files when you want the queue tracked in version control. Run -`dn kickstart --milestone 42` to work through unchecked items; use `--complete` -to drain the queue without prompts between tasks. See +`dn kickstart --milestone 42` to work through unchecked items; use +`--publish pr --complete` to drain the queue without prompts between tasks (each +item is published before the next). See [Completing GitHub Issues](/dn/completing-github-issues/#milestone-queues). ## Project base images diff --git a/src/content/docs/dn/task-list-and-sync.md b/src/content/docs/dn/task-list-and-sync.md index 2cb54da..c6742d4 100644 --- a/src/content/docs/dn/task-list-and-sync.md +++ b/src/content/docs/dn/task-list-and-sync.md @@ -73,7 +73,9 @@ dn todo done plans/auth.plan.md ``` When the ref is a GitHub issue, `dn` closes the issue with a comment. Use this -after work lands to keep the list and GitHub in sync. +after `dn land` (or after `--publish direct` when you want the issue closed) to +keep the list and GitHub in sync. Attended `dn kickstart` does not mark todo +items done on exit. ## `dn tidy` @@ -97,8 +99,11 @@ running the top item. If the list is empty, it can search the current repository for open issues and plan files, score them, write the list, and suggest the first item. -After a successful run, `dn` can mark the item done and continue to the next -one. +Attended kickstart exits after a successful run. It does not mark the queue item +done or ask to continue. Review the changes, run `dn land` when you are ready to +commit, then `dn todo done` to check the item off and close the GitHub issue if +applicable. For per-issue publish without a separate land step, use +`--publish pr` or `--publish direct`. ## `dn sync` diff --git a/src/content/docs/dn/workflows.md b/src/content/docs/dn/workflows.md index 433bea9..990a4a7 100644 --- a/src/content/docs/dn/workflows.md +++ b/src/content/docs/dn/workflows.md @@ -89,7 +89,9 @@ dn land plans/issue-123.plan.md --dry-run `land` discovers or accepts a `plans/*.plan.md` file, verifies its checklist, reviews current workspace changes, and uses the selected agent to group them -into logical conventional commits. On success, it removes the plan file. +into logical conventional commits. On success, it removes the plan file. Land +targets one plan at a time; for per-issue publish without stacking local +kickstarts, use `dn kickstart --publish pr|direct` instead. `--single` creates one deterministic commit without an agent. `--dry-run` previews the operation without committing, deleting a plan, or changing GitHub. @@ -318,12 +320,13 @@ the gambit file. dn meld --milestone 42 dn init stack 42 dn kickstart --milestone 42 --once -dn kickstart --milestone 42 --complete +dn kickstart --publish pr --milestone 42 --complete ``` `dn meld --milestone` writes a user-value-focused milestone description. `dn init stack` creates a prioritized execution queue. `--once` processes one -unchecked item; `--complete` processes all remaining items. +unchecked item; `--complete` processes all remaining items and requires +`--publish pr` or `--publish direct`. ## `dn sync`