@joshuafolkken/kit 1.1455.0 → 1.1514.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/settings.json +6 -6
- package/.claude/skills/dependency-update/SKILL.md +26 -55
- package/.claude/skills/epic-commands/SKILL.md +83 -156
- package/.claude/skills/epic-commands/epic-bundle.md +51 -79
- package/.claude/skills/epic-commands/execution-waves.md +43 -81
- package/.claude/skills/verify-ui/SKILL.md +24 -50
- package/.claude/skills/workflow-commands/SKILL.md +7 -9
- package/.claude/skills/workflow-commands/background-commands.md +31 -46
- package/.claude/skills/workflow-commands/backlogrun-child.md +65 -85
- package/.claude/skills/workflow-commands/backlogrun-lanes.md +86 -125
- package/.claude/skills/workflow-commands/backlogrun-park.md +68 -118
- package/.claude/skills/workflow-commands/backlogrun-progress.md +17 -28
- package/.claude/skills/workflow-commands/backlogrun-recovery.md +17 -26
- package/.claude/skills/workflow-commands/backlogrun-steps.md +35 -52
- package/.claude/skills/workflow-commands/backlogrun.md +31 -50
- package/.claude/skills/workflow-commands/chain-rule.md +31 -40
- package/.claude/skills/workflow-commands/delegation.md +12 -8
- package/.claude/skills/workflow-commands/entry-sequence.md +1 -3
- package/.claude/skills/workflow-commands/followup.md +55 -77
- package/.claude/skills/workflow-commands/fullrun-steps.md +3 -5
- package/.claude/skills/workflow-commands/fullrun.md +4 -6
- package/.claude/skills/workflow-commands/halfrun.md +3 -7
- package/.claude/skills/workflow-commands/into-target.md +1 -2
- package/.claude/skills/workflow-commands/issue-comments.md +43 -60
- package/.claude/skills/workflow-commands/issue-scout.md +3 -2
- package/.claude/skills/workflow-commands/kickoff.md +65 -74
- package/.claude/skills/workflow-commands/latest-gate.md +2 -6
- package/.claude/skills/workflow-commands/needs-human-review.md +2 -5
- package/.claude/skills/workflow-commands/observation-filing.md +59 -118
- package/.claude/skills/workflow-commands/observation-ledger.md +52 -112
- package/.claude/skills/workflow-commands/pre-gate-cut.md +88 -142
- package/.claude/skills/workflow-commands/prerequisite.md +11 -17
- package/.claude/skills/workflow-commands/progress-watcher.md +23 -33
- package/.claude/skills/workflow-commands/prrun.md +3 -5
- package/.claude/skills/workflow-commands/retrospective.md +35 -54
- package/.claude/skills/workflow-commands/split-assessment.md +32 -58
- package/.claude/skills/workflow-commands/target-repository.md +1 -2
- package/.claude/skills/workflow-commands/working-tree-hold.md +54 -73
- package/.codex/hooks.json +6 -6
- package/.github/actions/setup-node/action.yml +1 -1
- package/.github/workflows/ci.yml +1 -1
- package/.github/workflows/publish.yml +2 -2
- package/CLAUDE.md +7 -6
- package/cspell/index.yaml +7 -0
- package/dist/CLAUDE.md +7 -6
- package/dist/commands/document-section-cli.js +67 -34
- package/dist/hooks/batch-guard.js +6 -6
- package/dist/hooks/chunk-4KKD2UTK.js +66 -0
- package/dist/hooks/{chunk-GPLGZ6IC.js → chunk-6TS2JD6D.js} +14 -3
- package/dist/hooks/chunk-7DSBJVFH.js +50 -0
- package/dist/hooks/{chunk-5H4SSDSD.js → chunk-A65Y4YOR.js} +3 -3
- package/dist/hooks/{chunk-3C4XRYG6.js → chunk-APUO6U4J.js} +102 -19
- package/dist/hooks/{chunk-IX6TTTI6.js → chunk-EFXE6C37.js} +8 -22
- package/dist/hooks/chunk-GP4IEC4O.js +20 -0
- package/dist/hooks/chunk-JP45SOCJ.js +56 -0
- package/dist/hooks/{chunk-OLMO72ON.js → chunk-LAOV7NLM.js} +1 -1
- package/dist/hooks/chunk-M4HGZV7U.js +83 -0
- package/dist/hooks/{chunk-TBJFTSUY.js → chunk-O6GDRNJB.js} +9 -7
- package/dist/hooks/{chunk-HFGWYGUV.js → chunk-PF2NZL2A.js} +5 -5
- package/dist/hooks/{chunk-WNLVGT7E.js → chunk-PTICX4OL.js} +4 -5
- package/dist/hooks/{chunk-HHI6FO3R.js → chunk-RT27QRJW.js} +763 -1515
- package/dist/hooks/{chunk-7WQBPLUN.js → chunk-SYOTDYCI.js} +1149 -1095
- package/dist/hooks/{chunk-LIAFCXL7.js → chunk-TNUMY6NL.js} +1519 -1332
- package/dist/hooks/chunk-UPUZF3AN.js +279 -0
- package/dist/hooks/{chunk-Z4XI7CZS.js → chunk-WK6SMBIC.js} +1932 -784
- package/dist/hooks/codex-hook-adapter.js +17 -14
- package/dist/hooks/duplicate-read-guard.js +7 -7
- package/dist/hooks/format-edited.js +5 -4
- package/dist/hooks/inputs.json +302 -247
- package/dist/hooks/investigation-guard.js +8 -11
- package/dist/hooks/pretool-guard.js +16 -13
- package/dist/hooks/session-lang.js +372 -26
- package/dist/hooks/stop-guard.js +2593 -189
- package/dist/josh.js +2128 -282
- package/dist/managed-marker/index.js +1 -2
- package/dist/version/index.js +15 -12
- package/eslint/base.js +2 -1
- package/eslint/rules/unicorn.js +16 -0
- package/lefthook/base.yml +5 -3
- package/package.json +14 -12
- package/prompts/coding-standards.md +12 -22
- package/prompts/collaboration-workflow/file-edits.md +25 -45
- package/prompts/collaboration-workflow/gh-rest.md +19 -36
- package/prompts/collaboration-workflow/glossary.md +5 -7
- package/prompts/collaboration-workflow/issue-citation.md +6 -14
- package/prompts/collaboration-workflow/issue-template.md +40 -32
- package/prompts/collaboration-workflow/lane-instructions.md +35 -0
- package/prompts/collaboration-workflow/operating-rules.md +33 -46
- package/prompts/collaboration-workflow/output-bounds.md +15 -15
- package/prompts/collaboration-workflow/overview.md +14 -19
- package/prompts/collaboration-workflow/plan-comment.md +13 -13
- package/prompts/collaboration-workflow/principles.md +57 -54
- package/prompts/collaboration-workflow/proposal-request.md +1 -9
- package/prompts/collaboration-workflow/report-format.md +41 -49
- package/prompts/collaboration-workflow/residency.md +15 -11
- package/prompts/collaboration-workflow/rule-delivery.md +7 -15
- package/prompts/collaboration-workflow/shell-body.md +10 -20
- package/prompts/collaboration-workflow/turn-batching.md +8 -14
- package/prompts/collaboration-workflow/upstream-interrupt.md +26 -34
- package/prompts/collaboration-workflow/wip-cap.md +26 -32
- package/prompts/collaboration-workflow.md +25 -25
- package/prompts/refactoring.md +33 -43
- package/prompts/review-rubric.md +84 -129
- package/prompts/review.md +110 -141
- package/prompts/sonar-hotspot-handling.md +22 -50
- package/prompts/testing-guide.md +48 -99
- package/scripts/adopt/adopt-toolkits.ts +2 -4
- package/scripts/agent/agent-argv.ts +20 -4
- package/scripts/agent/agent-exit-record.ts +23 -1
- package/scripts/agent/agent-role-profile.ts +101 -45
- package/scripts/agent/agent-safe-text.ts +60 -0
- package/scripts/agent/claude-agent-argv.ts +14 -0
- package/scripts/agent/codex-agent-argv.ts +9 -2
- package/scripts/agent/lane-instructions.ts +144 -0
- package/scripts/backlog/backlog-budget-cli.ts +1 -2
- package/scripts/backlog/backlog-budget.ts +4 -4
- package/scripts/backlog/backlog-drive-carried.ts +26 -0
- package/scripts/backlog/backlog-drive-cli.ts +10 -5
- package/scripts/backlog/backlog-drive-named.ts +3 -5
- package/scripts/backlog/backlog-drive-restore.ts +28 -2
- package/scripts/backlog/backlog-drive-seats.ts +27 -0
- package/scripts/backlog/backlog-drive.ts +11 -6
- package/scripts/backlog/backlog-occupied.ts +56 -0
- package/scripts/backlog/backlog-ready.ts +59 -15
- package/scripts/behavior/behavior-rules.ts +3 -2
- package/scripts/cost-runtime/codex-usage.ts +4 -2
- package/scripts/cost-runtime/cost-cli.ts +1 -2
- package/scripts/delegation/duplicate-read-guard.ts +2 -2
- package/scripts/delegation/investigation-guard.ts +15 -65
- package/scripts/delegation/investigation-reads.ts +1 -2
- package/scripts/discovery/repo-discovery.ts +4 -2
- package/scripts/discovery/repo-origin.ts +2 -4
- package/scripts/doctor/doctor-logic.ts +6 -3
- package/scripts/document/document-byte-budget.ts +28 -27
- package/scripts/document/document-byte-check.ts +1 -2
- package/scripts/document/document-section-cli.ts +17 -5
- package/scripts/document/entry-read-budget.ts +3 -3
- package/scripts/document/read-set-cli.ts +4 -1
- package/scripts/epic/epic-audit-orphans.ts +5 -8
- package/scripts/epic/epic-audit-rationale.ts +8 -2
- package/scripts/epic/epic-audit.ts +52 -1
- package/scripts/epic/epic-bundle-cli.ts +1 -2
- package/scripts/epic/epic-bundle-evidence.ts +49 -26
- package/scripts/epic/epic-bundle-referenced.ts +14 -3
- package/scripts/epic/epic-bundle.ts +17 -9
- package/scripts/epic/epic-chains.ts +6 -2
- package/scripts/epic/epic-close-comment.ts +1 -2
- package/scripts/followup/git-followup-workflow.ts +19 -1
- package/scripts/gate/check-inputs.ts +129 -0
- package/scripts/gate/check-reuse.ts +162 -0
- package/scripts/gate/core-budget.ts +93 -44
- package/scripts/gate/core-wait.ts +130 -0
- package/scripts/gate/free-cores.ts +49 -0
- package/scripts/gate/gate-ledger.ts +17 -3
- package/scripts/gate/gate-plan.ts +23 -1
- package/scripts/gate/gate-report.ts +15 -2
- package/scripts/gate/gate-run-steps.ts +150 -0
- package/scripts/gate/held-mark.ts +55 -0
- package/scripts/gate/machine-capacity.ts +70 -11
- package/scripts/gate/pre-commit-type-check.ts +14 -1
- package/scripts/gate/verification-gate.ts +65 -127
- package/scripts/gh/git-gh-issue-rest.ts +1 -0
- package/scripts/gh/git-gh-issue-write.ts +24 -2
- package/scripts/gh/git-pr.ts +19 -3
- package/scripts/git/git-common-directory.ts +3 -3
- package/scripts/git/git-diff-reads.ts +16 -9
- package/scripts/git/git-execa-error.ts +1 -2
- package/scripts/git/main-merge-regenerate.ts +78 -0
- package/scripts/git/main-merge.ts +14 -5
- package/scripts/hooks/batch-guard.ts +5 -8
- package/scripts/hooks/format-edited-file.ts +10 -4
- package/scripts/hooks/pre-commit-lint.ts +91 -0
- package/scripts/hooks/pre-push-unit.ts +15 -4
- package/scripts/hooks/pretool-guard.ts +48 -79
- package/scripts/hooks/reserved-run.ts +1 -0
- package/scripts/hooks/run-hook.sh +10 -12
- package/scripts/hooks/step-zero-notice.ts +3 -2
- package/scripts/hooks/stop-actions.ts +204 -0
- package/scripts/hooks/stop-guard.ts +62 -21
- package/scripts/init/hook-command-rewrite.ts +6 -2
- package/scripts/init/hook-launch.ts +12 -7
- package/scripts/init/init-logic-deploy-vps.ts +4 -2
- package/scripts/issue/behavior-change-lint.ts +12 -6
- package/scripts/issue/expected-effect-lint.ts +59 -0
- package/scripts/issue/issue-cite-cli.ts +35 -15
- package/scripts/issue/issue-classification.ts +1 -1
- package/scripts/issue/issue-lint-cli.ts +5 -3
- package/scripts/issue/issue-scout-cli.ts +22 -16
- package/scripts/issue/markdown-section.ts +19 -5
- package/scripts/josh/command-usage.ts +110 -0
- package/scripts/josh/file-map-stamp.ts +1 -3
- package/scripts/josh/hook-decision.ts +17 -2
- package/scripts/josh/josh-command-map.ts +2 -0
- package/scripts/josh/josh-command-types.ts +55 -9
- package/scripts/josh/josh-commands-ai.ts +13 -0
- package/scripts/josh/josh-commands-development.ts +1 -1
- package/scripts/josh/josh-commands-hooks.ts +6 -0
- package/scripts/josh/josh-commands-lane.ts +10 -1
- package/scripts/josh/josh-commands-workflow.ts +5 -0
- package/scripts/josh/josh-logic.ts +6 -15
- package/scripts/josh/josh-usage-automation.ts +121 -0
- package/scripts/josh/josh-usage-backlog.ts +180 -0
- package/scripts/josh/josh-usage-developer.ts +230 -0
- package/scripts/josh/josh-usage-hooks.ts +38 -0
- package/scripts/josh/josh-usage-issue.ts +205 -0
- package/scripts/josh/josh-usage-review.ts +101 -0
- package/scripts/josh/josh-usage-run.ts +252 -0
- package/scripts/josh/josh-usage-session.ts +238 -0
- package/scripts/josh/josh-usage-workflow.ts +212 -0
- package/scripts/josh/josh.ts +14 -5
- package/scripts/josh/package-directory.ts +20 -0
- package/scripts/lane/lane-await.ts +3 -2
- package/scripts/lane/lane-capacity.ts +8 -2
- package/scripts/lane/lane-check-stats.ts +56 -0
- package/scripts/lane/lane-child-invocation.ts +49 -5
- package/scripts/lane/lane-dispatch.ts +3 -3
- package/scripts/lane/lane-guard-policy.ts +5 -5
- package/scripts/lane/lane-handoff.ts +8 -1
- package/scripts/lane/lane-install.ts +12 -4
- package/scripts/lane/lane-ledger.ts +52 -1
- package/scripts/lane/lane-limit-cli.ts +8 -9
- package/scripts/lane/lane-load.ts +9 -2
- package/scripts/lane/lane-measure-cli.ts +4 -0
- package/scripts/lane/lane-parked.ts +18 -0
- package/scripts/lane/lane-preserve.ts +29 -1
- package/scripts/lane/lane-process-load.ts +125 -0
- package/scripts/lane/lane-process-stats.ts +93 -0
- package/scripts/lane/lane-registry.ts +17 -10
- package/scripts/lane/lane-restart.ts +5 -26
- package/scripts/lane/lane-session-action.ts +146 -0
- package/scripts/lane/lane-session-broker.ts +68 -125
- package/scripts/lane/lane-spent.ts +14 -3
- package/scripts/lane/lane-stats.ts +1 -0
- package/scripts/lane/lane-withdraw-cli.ts +71 -0
- package/scripts/lane/lane-withdraw.ts +182 -0
- package/scripts/lint/format.ts +4 -4
- package/scripts/lint/lint-parallel.ts +10 -3
- package/scripts/lint/lint-related-scope.ts +4 -1
- package/scripts/managed-marker/managed-marker-logic.ts +1 -2
- package/scripts/notify/telegram-test.ts +10 -5
- package/scripts/overrides/lockfile-overrides.ts +1 -3
- package/scripts/propagate/propagate.ts +1 -2
- package/scripts/release/release-progress.ts +3 -2
- package/scripts/report/report-format-reference.ts +2 -0
- package/scripts/report/report-lint.ts +7 -4
- package/scripts/review/acceptance-map-check.ts +61 -0
- package/scripts/review/acceptance-map.ts +205 -0
- package/scripts/review/review-brief-cli.ts +1 -1
- package/scripts/review/review-record-cli.ts +6 -2
- package/scripts/rules/agent-model.ts +59 -0
- package/scripts/rules/delivered-rules.ts +11 -2
- package/scripts/rules/destructive-command.ts +6 -9
- package/scripts/rules/direct-filing.ts +3 -7
- package/scripts/rules/early-heartbeat.ts +7 -18
- package/scripts/rules/file-body.ts +6 -13
- package/scripts/rules/filing-cap.ts +4 -6
- package/scripts/rules/firing-point.ts +6 -5
- package/scripts/rules/git-force.ts +5 -9
- package/scripts/rules/guard-remedy.ts +117 -0
- package/scripts/rules/implementation-cut.ts +37 -35
- package/scripts/rules/index-guard.ts +4 -7
- package/scripts/rules/issue-comments.ts +67 -16
- package/scripts/rules/josh-git-bare.ts +3 -6
- package/scripts/rules/lane-background.ts +10 -21
- package/scripts/rules/lane-carry-conflict.ts +7 -17
- package/scripts/rules/lane-interactive-ask.ts +6 -11
- package/scripts/rules/lane-park.ts +5 -13
- package/scripts/rules/lane-split-park.ts +2 -7
- package/scripts/rules/lane-switch-main.ts +9 -12
- package/scripts/rules/last-prompt.ts +50 -5
- package/scripts/rules/oracle-consulted.ts +4 -5
- package/scripts/rules/oracle-list-cli.ts +7 -0
- package/scripts/rules/piped-verification.ts +84 -32
- package/scripts/rules/poll-loop.ts +7 -17
- package/scripts/rules/pre-gate-cut.ts +7 -21
- package/scripts/rules/prior-comment-read.ts +7 -5
- package/scripts/rules/protected-files.ts +5 -9
- package/scripts/rules/raw-field-body.ts +3 -7
- package/scripts/rules/rule-body-guard.ts +4 -11
- package/scripts/rules/rule-list.ts +4 -1
- package/scripts/rules/rule-registry-rows.ts +10 -0
- package/scripts/rules/rule-registry.ts +7 -4
- package/scripts/rules/rule-rewrite.ts +114 -0
- package/scripts/rules/rule-value.ts +7 -1
- package/scripts/rules/run-tail-rule.ts +6 -22
- package/scripts/rules/shell-body-trigger.ts +4 -6
- package/scripts/rules/shell-segments.ts +22 -0
- package/scripts/rules/stop-decision.ts +77 -0
- package/scripts/rules/stop-rules.ts +164 -77
- package/scripts/rules/tail-commands.ts +15 -1
- package/scripts/rules/test-declared-commit.ts +4 -10
- package/scripts/rules/third-party-write.ts +5 -10
- package/scripts/rules/worktree-guard.ts +5 -12
- package/scripts/run/board/run-board-cli.ts +2 -0
- package/scripts/run/board/run-board-closed.ts +8 -2
- package/scripts/run/board/run-board-github.ts +19 -3
- package/scripts/run/board/run-board-header.ts +4 -1
- package/scripts/run/board/run-board-idle.ts +31 -0
- package/scripts/run/board/run-board-labels.ts +2 -0
- package/scripts/run/board/run-board-layout.ts +1 -1
- package/scripts/run/board/run-board-read.ts +25 -12
- package/scripts/run/board/run-board-reason.ts +17 -4
- package/scripts/run/board/run-board-render-legend.ts +1 -0
- package/scripts/run/board/run-board-render-slot.ts +1 -1
- package/scripts/run/board/run-board-render-waits.ts +41 -0
- package/scripts/run/board/run-board-render.ts +6 -1
- package/scripts/run/board/run-board-row-yield.ts +1 -0
- package/scripts/run/board/run-board-state.ts +9 -0
- package/scripts/run/board/run-board-status.ts +89 -23
- package/scripts/run/board/run-board-thanks.ts +7 -2
- package/scripts/run/board/run-board-tick.ts +37 -8
- package/scripts/run/carry/run-carry-args.ts +1 -3
- package/scripts/run/carry/run-carry-conversation.ts +7 -2
- package/scripts/run/cut/run-cut-cli.ts +18 -22
- package/scripts/run/cut/run-cut-decline.ts +72 -0
- package/scripts/run/cut/run-cut-ready.ts +74 -0
- package/scripts/run/cut/run-cut-report.ts +29 -0
- package/scripts/run/cut/run-cut.ts +10 -1
- package/scripts/run/detached-launch.ts +23 -4
- package/scripts/run/entry/run-entry-cli.ts +8 -1
- package/scripts/run/event/run-event-render.ts +1 -0
- package/scripts/run/event/run-event-scope.ts +19 -1
- package/scripts/run/event/run-event-stream-emit.ts +13 -6
- package/scripts/run/event/run-event-stream.ts +4 -0
- package/scripts/run/hold/run-hold-cli.ts +14 -3
- package/scripts/run/hold/run-hold-session.ts +46 -0
- package/scripts/run/hold/run-hold.ts +13 -4
- package/scripts/run/launch-priority.ts +32 -0
- package/scripts/run/merge/run-merge-cli.ts +16 -42
- package/scripts/run/merge/run-merge-ship.ts +59 -1
- package/scripts/run/merge/run-merge-signals.ts +99 -0
- package/scripts/run/merge/run-merge-steps.ts +11 -1
- package/scripts/run/merge/run-merge.ts +22 -9
- package/scripts/run/run-ending.ts +31 -3
- package/scripts/run/run-liveness.ts +1 -1
- package/scripts/run/run-parent-cut-hook.ts +5 -10
- package/scripts/run/run-poll-hook.ts +157 -0
- package/scripts/run/run-preflight.ts +1 -2
- package/scripts/run/run-step-cli.ts +22 -15
- package/scripts/run/run-step-section.ts +85 -0
- package/scripts/run/run-stop-notify.ts +1 -2
- package/scripts/run/run-watcher-guard.ts +6 -3
- package/scripts/run/ship/run-ship-cli.ts +5 -12
- package/scripts/run/ship/run-ship-detach.ts +9 -0
- package/scripts/run/ship/run-ship-next.ts +10 -2
- package/scripts/run/ship/run-ship-overlap.ts +195 -0
- package/scripts/run/ship/run-ship-pre-detach.ts +33 -15
- package/scripts/run/ship/run-ship-preflight.ts +28 -2
- package/scripts/run/ship/run-ship-return.ts +31 -7
- package/scripts/run/ship/run-ship-review-steps.ts +25 -14
- package/scripts/run/ship/run-ship-review.ts +15 -2
- package/scripts/run/ship/run-ship-steps.ts +1 -1
- package/scripts/run/ship/run-ship-stop-context.ts +206 -0
- package/scripts/run/ship/run-ship-sync.ts +14 -6
- package/scripts/run/tidy/run-tidy-cli.ts +3 -3
- package/scripts/run/tidy/run-tidy-lanes.ts +3 -2
- package/scripts/safe-chain/project-config.ts +7 -2
- package/scripts/sync/sync-hook-safety.ts +8 -2
- package/scripts/test/test-e2e-guard.ts +30 -5
- package/scripts/test/test-unit-guard.ts +16 -1
- package/scripts/test/unit-worker-share.ts +26 -3
- package/scripts/time-runtime/time-batch-guard.ts +3 -3
- package/scripts/time-runtime/time-hook-transcript.ts +3 -2
- package/scripts/time-runtime/time-shell.ts +39 -4
- package/scripts/time-runtime/time-spans.ts +1 -0
- package/scripts/time-runtime/time-tool-call.ts +7 -0
- package/scripts/version/effective-upstream.ts +3 -4
- package/scripts/version/kit-version-config.ts +8 -2
- package/scripts/version/latest-corepack.ts +1 -2
- package/scripts/version/release-hold.ts +11 -4
- package/scripts/version/version-commands.ts +12 -4
- package/templates/gitignore +6 -2
- package/dist/hooks/chunk-D5QBTOCZ.js +0 -68
- package/dist/hooks/chunk-UT7YC3N2.js +0 -56
|
@@ -1,113 +1,99 @@
|
|
|
1
1
|
# `backlogrun` — running a child (shared mechanics, delegation, liveness, session setup)
|
|
2
2
|
|
|
3
|
-
Point-of-use, read one section at a time from `backlogrun.md` → "The
|
|
3
|
+
Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow".
|
|
4
4
|
|
|
5
5
|
## Running a child — the shared mechanics
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
This file is the single source of how **one child** runs — a named single-issue item, a named epic's
|
|
8
|
+
child and a bare backlog child all run the same `fullrun`. A named epic runs these mechanics over its
|
|
9
|
+
children until every one is processed, then the run advances to the next named item.
|
|
8
10
|
|
|
9
11
|
## When `#N` is not an epic
|
|
10
12
|
|
|
11
|
-
`backlogrun
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
"A prerequisite discovered mid-run" do — `git stash push -u -m "..."` with the `-u`, the
|
|
20
|
-
`gh api repos/{owner}/{repo}/issues/<N>/comments` post that records the stash, and
|
|
21
|
-
`pnpm josh run:release <N>`, which removes the label with the hold.
|
|
13
|
+
`backlogrun #<N>` on an Issue with no task list runs `#<N>` as a `fullrun` and finishes. A prerequisite
|
|
14
|
+
or a split found mid-run does **not** stop it:
|
|
15
|
+
|
|
16
|
+
1. File the new Issue(s) — `route:split` for a split, `route:tier-a` for a prerequisite — no
|
|
17
|
+
confirmation.
|
|
18
|
+
2. **Stash and remove `in-progress`**, as steps 2 and 4 of "A prerequisite discovered mid-run" do:
|
|
19
|
+
`git stash push -u -m "..."`, a `gh api repos/{owner}/{repo}/issues/<N>/comments` post recording the
|
|
20
|
+
stash, and `pnpm josh run:release <N>`.
|
|
22
21
|
3. **Ask `pnpm josh epic:bundle <N>` whether an epic already tracks `#<N>` before creating one.**
|
|
23
22
|
|
|
24
23
|
| Answer | What to do |
|
|
25
24
|
| --- | --- |
|
|
26
|
-
| An epic `#<E>` already tracks `#<N>` | `pnpm josh epic --add <E> <P> --before <N>`
|
|
27
|
-
| No epic tracks it | Create one
|
|
28
|
-
| **The command could not answer**
|
|
25
|
+
| An epic `#<E>` already tracks `#<N>` | `pnpm josh epic --add <E> <P> --before <N>` (prerequisite) or `--add <E> <N1> ...` (split). **Do not create a second epic**; continue against `#<E>` |
|
|
26
|
+
| No epic tracks it | Create one (table below) |
|
|
27
|
+
| **The command could not answer** | Park `#<N>` with `needs-decision` and report — "could not tell" is not "no epic" |
|
|
28
|
+
|
|
29
|
+
"Could not answer" is a non-zero exit, `Could not confirm which epic already tracks these — do not
|
|
30
|
+
place this issue in one.`, or a `⚠ The epic listing …` truncation warning (`hit its …-epic cap` /
|
|
31
|
+
`stopped at the …-issue page ceiling`) above `Nothing to bundle.`. `⚠ Could not read #N.` voids
|
|
32
|
+
nothing, and a definitive answer stands beside a warning.
|
|
29
33
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
what was found, because `--ordered` makes the argument order the dependency chain:
|
|
34
|
+
`#<N>` is itself one of the deliverables (the keep-as-a-child arm of `split-assessment.md`).
|
|
35
|
+
`--ordered` makes the argument order the dependency chain:
|
|
33
36
|
|
|
34
37
|
| Found | Command |
|
|
35
38
|
| --- | --- |
|
|
36
|
-
| A prerequisite `<P>` | `pnpm josh epic "<title>" <P> <N> --ordered` — the prerequisite
|
|
39
|
+
| A prerequisite `<P>` | `pnpm josh epic "<title>" <P> <N> --ordered` — the prerequisite **first** |
|
|
37
40
|
| A split into independent children | `pnpm josh epic "<title>" <N> <N1> ...` — **no `--ordered`** |
|
|
38
|
-
| A split whose children do have an order | `pnpm josh epic "<title>" ... --ordered`,
|
|
39
|
-
|
|
40
|
-
4. **Run `pnpm josh epic:audit <E>` now**, not earlier — there is no epic to audit until step 3.
|
|
41
|
-
5. **Do not stop.** Continue into the loop below against the new epic `#<E>`.
|
|
42
|
-
|
|
43
|
-
**Nothing found means no epic.** If `#<N>` reaches its merge without a prerequisite or a split turning
|
|
44
|
-
up, the run finishes there. An epic is created only when there is a second child to put in it.
|
|
41
|
+
| A split whose children do have an order | `pnpm josh epic "<title>" ... --ordered`, in that order |
|
|
45
42
|
|
|
46
|
-
**
|
|
47
|
-
|
|
43
|
+
4. **Run `pnpm josh epic:audit <E>` now** — there is no epic to audit before step 3.
|
|
44
|
+
5. **Do not stop.** Continue into the loop against `#<E>`.
|
|
48
45
|
|
|
49
|
-
**
|
|
50
|
-
|
|
51
|
-
|
|
46
|
+
- **Nothing found means no epic** — the run finishes at `#<N>`'s merge.
|
|
47
|
+
- **Every guard applies unchanged** — 30 children, 10 Issues filed, 3 consecutive failures.
|
|
48
|
+
- **`fullrun` does not promote itself** — it files and **stops** (`split-assessment.md` → "Finding a
|
|
49
|
+
split mid-run stops the run"). `josh epic:next` still refuses an Issue with no task list.
|
|
50
|
+
- **A bare Issue named beside an epic is a mistyped command.** Named alone, the refusal is the answer;
|
|
51
|
+
among several, it is **skipped** — `backlogrun #<E> --only #<N>` exits 0, notes the skip on stderr
|
|
52
|
+
and **never runs `#<N>`**. To do both, type `backlogrun #<N>` after the epic.
|
|
52
53
|
|
|
53
|
-
**`josh epic:next` is not changed by any of this.** It still refuses an Issue with no task list; the
|
|
54
|
-
acceptance of a bare Issue belongs to `backlogrun`.
|
|
55
|
-
|
|
56
|
-
**Naming a bare Issue beside an epic is a mistyped command rather than a second entry.** Where one
|
|
57
|
-
reference is named, the refusal is the whole answer. Where several are, a task-listless reference is
|
|
58
|
-
**skipped** so the other epics keep running — `backlogrun #<E> --only #<N>` with `#<N>` an ordinary Issue exits
|
|
59
|
-
0, notes the skip on standard error, and **never runs `#<N>`**. A run that means to do both types
|
|
60
|
-
`backlogrun #<N>` on its own after the epic.
|
|
61
54
|
## Each child runs in a delegated unit
|
|
62
55
|
|
|
63
|
-
**
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
Where no isolated unit exists, run the child in the parent's context; the hand-off is still asked at
|
|
70
|
-
every merge. Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why each child runs in a
|
|
71
|
-
delegated unit".
|
|
72
|
-
|
|
73
|
-
**The parent reads GitHub, never the summary** — `pnpm josh issue:state <N>` (or `run:merge`) is the
|
|
74
|
-
verifier; **never advance the loop on the summary alone**.
|
|
56
|
+
**Whatever offers a child — the loop, or a person clearing a label — the child is handed to a lane,
|
|
57
|
+
never run in the parent's context.** `pnpm josh delegate epic-child` answers `delegate`; the unit is a
|
|
58
|
+
detached process from `pnpm josh lane:launch` (`backlogrun-lanes.md` → "Opening one lane and
|
|
59
|
+
dispatching its child") with the CLI's `worker` profile — Claude Code defaults to Anthropic
|
|
60
|
+
`claude-opus-5-5` / `medium` (`docs/josh-commands-run.md` → "`josh lane:dispatch`"). With no isolated
|
|
61
|
+
unit, run the child in the parent's context and still ask the hand-off at every merge.
|
|
75
62
|
|
|
76
|
-
**The
|
|
77
|
-
|
|
63
|
+
- **The parent reads GitHub, never the summary** — `pnpm josh issue:state <N>` (or `run:merge`)
|
|
64
|
+
verifies; **never advance the loop on the summary alone**.
|
|
65
|
+
- **The brief names the invocation it descends from** — e.g. `backlogrun #<E> --only`, the child
|
|
66
|
+
number, and that it runs as `fullrun #<N>` under that authorization; the unit refuses a brief without
|
|
67
|
+
it.
|
|
78
68
|
|
|
79
69
|
### What the summary carries, and how long it may be
|
|
80
70
|
|
|
81
|
-
**
|
|
82
|
-
Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why the summary is bounded the way it is".
|
|
71
|
+
**Only what GitHub does not, in at most 25 lines; the brief states the bound.**
|
|
83
72
|
|
|
84
|
-
- **Kept**: `Cause` / `Fix` / `Result`; every verification
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
- **Cut**: the changed-file list, per-round review detail,
|
|
73
|
+
- **Kept**: `Cause` / `Fix` / `Result`; every verification not closed the ordinary way, named as such;
|
|
74
|
+
observations that could bite later — **a child's only route for one** (`observation-filing.md` → "A
|
|
75
|
+
delegated child does not take this route"); decisions not yet logged; what was left undone, on whose
|
|
76
|
+
authority.
|
|
77
|
+
- **Cut**: the changed-file list, per-round review detail, restated rules.
|
|
89
78
|
|
|
90
79
|
The person-facing report (`prompts/collaboration-workflow/report-format.md` → 「完了報告(セッション向け)」)
|
|
91
80
|
is unchanged.
|
|
92
81
|
|
|
93
82
|
## A delegated unit that stopped without reporting
|
|
94
83
|
|
|
95
|
-
**Hand the child
|
|
96
|
-
|
|
97
|
-
`backlogrun-recovery.md` → "A delegated unit that
|
|
98
|
-
`pnpm josh run:liveness`.
|
|
84
|
+
**Hand the child off without blocking, and wait on `pnpm josh lane:await <N>`** — a stopped unit
|
|
85
|
+
leaves no notification, so the await's exit is the wake. Once its
|
|
86
|
+
output is unchanged for the silent-unit window, read `backlogrun-recovery.md` → "A delegated unit that
|
|
87
|
+
stopped without reporting" and ask `pnpm josh run:liveness`.
|
|
99
88
|
|
|
100
89
|
## Audit before the first child
|
|
101
90
|
|
|
102
|
-
Run `pnpm josh epic:audit <E>` before
|
|
103
|
-
|
|
104
|
-
stop the run; warnings are read and carried on past. Fixing what it finds is Tier A. Rationale:
|
|
105
|
-
`docs/maintainers/backlogrun-child-rationale.md` → "Why the audit runs before the first child".
|
|
91
|
+
Run `pnpm josh epic:audit <E>` before the first child; a run begun from a bare Issue audits when it
|
|
92
|
+
creates the epic. Errors stop the run; warnings are read and passed. Fixing a finding is Tier A.
|
|
106
93
|
|
|
107
94
|
## `josh latest` runs once per session, not once per child
|
|
108
95
|
|
|
109
|
-
|
|
110
|
-
back a child number — before implementing that child — and never again:
|
|
96
|
+
Ask once, the first time the loop hands back a child number, before implementing it:
|
|
111
97
|
|
|
112
98
|
```bash
|
|
113
99
|
pnpm josh latest:scope # → required | skip ; the reason on stderr
|
|
@@ -117,20 +103,14 @@ pnpm josh latest # on `required` only
|
|
|
117
103
|
pnpm josh stash:pop "backlogrun: josh latest #<N>" # only if you stashed above — by message, not a positional pop
|
|
118
104
|
```
|
|
119
105
|
|
|
120
|
-
On `required`, load the `dependency-update` skill; `latest-gate.md` is the single source.
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
primary checkout (`backlogrun-lanes.md` → "Once per repository, before the first lane opens").
|
|
125
|
-
|
|
126
|
-
Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why `josh latest` is hoisted to the
|
|
127
|
-
session".
|
|
106
|
+
On `required`, load the `dependency-update` skill; `latest-gate.md` is the single source. A resumed
|
|
107
|
+
`backlogrun` asks again. **The lock file lands with the first child's `pnpm josh git -y`**; fix a
|
|
108
|
+
failing bump forward. **Never inside a lane** (`pnpm josh latest:guard` refuses) — the parent runs it
|
|
109
|
+
in the primary checkout (`backlogrun-lanes.md` → "Once per repository, before the first lane opens").
|
|
128
110
|
|
|
129
111
|
## Preflight — the child's claim asks it
|
|
130
112
|
|
|
131
|
-
`pnpm josh run:hold <N>`, the
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
`docs/maintainers/backlogrun-child-rationale.md` → "Why the preflight is part of the claim".
|
|
136
|
-
|
|
113
|
+
`pnpm josh run:hold <N>`, the child's first call, checks for an interrupted run's leftovers before
|
|
114
|
+
claiming the tree and prints the step for each answer (`reclaim` / `resume` / `park`) on stderr —
|
|
115
|
+
follow it, and report a reclaim or resume with its stash reference (`docs/josh-commands-run.md` →
|
|
116
|
+
"`josh run:hold`").
|
|
@@ -1,14 +1,12 @@
|
|
|
1
1
|
# `backlogrun` — lanes and concurrency
|
|
2
2
|
|
|
3
|
-
Point-of-use, read one section at a time from `backlogrun.md` → "The
|
|
3
|
+
Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow".
|
|
4
4
|
|
|
5
5
|
## Concurrency: as many children per repository as it has free lanes
|
|
6
6
|
|
|
7
|
-
**One session per repository**, each running only its own repository's children
|
|
8
|
-
|
|
9
|
-
`.claude/skills/epic-commands/SKILL.md` → "
|
|
10
|
-
repository is `.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories". Rationale:
|
|
11
|
-
`docs/maintainers/backlogrun-lanes-rationale.md` → "Why the lane ceiling is shaped the way it is".
|
|
7
|
+
**One session per repository**, each running only its own repository's children. The lane ceiling is
|
|
8
|
+
`.claude/skills/epic-commands/SKILL.md` → "An `in-progress` issue occupies a lane"; a dependency that
|
|
9
|
+
crosses a repository is `.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories".
|
|
12
10
|
|
|
13
11
|
## A solo run
|
|
14
12
|
|
|
@@ -19,65 +17,49 @@ it a defect (not an improvement, refactor, removal or feature)? Is it in kit's o
|
|
|
19
17
|
(lint / type check / spell check / unit tests), the code review, the pre-push hook, or the merge
|
|
20
18
|
checks — not a consumer repository's CI or template? Does it, on `main` now, make unrelated PRs
|
|
21
19
|
answer wrongly (a false green or a false red)? All three, and the issue carries `run:solo`; any one
|
|
22
|
-
missing, and it carries `run:lane`. `backlog:next` and `epic:next --lanes` answer `triage` for an
|
|
23
|
-
with neither, so
|
|
24
|
-
|
|
25
|
-
nobody's result trustworthy.** This section is the rule's single source; rationale:
|
|
26
|
-
`docs/maintainers/wip-cap-rationale.md` → "Why a solo run"; provenance:
|
|
27
|
-
`docs/maintainers/backlogrun-lanes-rationale.md` → "Where each rule came from".
|
|
20
|
+
missing, and it carries `run:lane`. `backlog:next` and `epic:next --lanes` answer `triage` for an
|
|
21
|
+
issue with neither, so a filed issue carries one of the two from its filing. **It stops the other
|
|
22
|
+
lanes for one reason only: a batch run on broken verification leaves nobody's result trustworthy.**
|
|
28
23
|
|
|
29
24
|
## Lanes — running more than one child at a time
|
|
30
25
|
|
|
31
|
-
`pnpm josh epic:next <E> --repo <owner/repo> --lanes` answers
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
`
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
`
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
**A lane's branch is `<N>-lane`, and the issue number leads it so that the commit path accepts it.**
|
|
54
|
-
**Never switch the lane to another branch** — a switched lane loses its seat, its listing and its
|
|
55
|
-
isolation. So `epic:next` is asked **with** `--lanes`, and everything below runs as written. Rationale:
|
|
56
|
-
`docs/maintainers/backlogrun-lanes-rationale.md` → "Why the lane branch is `<N>-lane` and never
|
|
57
|
-
switched".
|
|
58
|
-
|
|
59
|
-
**Report the throughput gain only with its merge-race cost** — every overlap that becomes a conflict
|
|
60
|
-
costs a resolution, a re-run gate and a review (`backlogrun-recovery.md` → "Conflicts are not predicted"). Rationale:
|
|
61
|
-
`docs/maintainers/backlogrun-lanes-rationale.md` → "Why lanes cost as well as buy throughput".
|
|
26
|
+
`pnpm josh epic:next <E> --repo <owner/repo> --lanes` answers **one issue number per line**, up to the
|
|
27
|
+
free lanes. Each child runs in a **lane**: a linked work tree with its own branch, `.env` and ports
|
|
28
|
+
(`docs/josh-commands-run.md` → "`josh lane:open` / `josh lane:close` / `josh lane:list` / `josh
|
|
29
|
+
lane:prune`"). **Implementation, the verification gate and the review run in parallel; the merges
|
|
30
|
+
stay serial.**
|
|
31
|
+
|
|
32
|
+
**A lane child may cut its own turn before the gate** — `pre-gate-cut.md`, the single source. The
|
|
33
|
+
child is told apart from a person, and handed its resume stage, by `JOSH_LANE_CHILD`
|
|
34
|
+
(`pre-gate-cut.md` → "The dispatch mark" and "The stage is passed to the resumed child").
|
|
35
|
+
|
|
36
|
+
**A lane's review does not inherit the lane, and `pnpm josh review:brief` is what closes that**: it
|
|
37
|
+
prints the lane's root, branch and HEAD, targets written `git -C <root> …`, and a nonce the review
|
|
38
|
+
attests with `pnpm josh review:attest <nonce>`. **The child asks `pnpm josh review:attest --check`
|
|
39
|
+
before it counts a round**, and `pnpm josh followup` asks again before merging; `missing` and
|
|
40
|
+
`mismatch` are refusals. A clean round is checked hardest.
|
|
41
|
+
|
|
42
|
+
**A lane's branch is `<N>-lane`. Never switch the lane to another branch** — it loses its seat,
|
|
43
|
+
listing and isolation. So `epic:next` is asked **with** `--lanes`.
|
|
44
|
+
|
|
45
|
+
**Report the throughput gain only with its merge-race cost** (`backlogrun-recovery.md` → "Conflicts
|
|
46
|
+
are not predicted").
|
|
62
47
|
|
|
63
48
|
### Once per repository, before the first lane opens
|
|
64
49
|
|
|
65
|
-
In the **primary checkout**, in
|
|
66
|
-
|
|
67
|
-
|
|
50
|
+
In the **primary checkout**, in order, never per lane: `pnpm josh ms`; `pnpm josh latest:scope` and the
|
|
51
|
+
update on `required` (`backlogrun-child.md` → "`josh latest` runs once per session, not once per
|
|
52
|
+
child"); `pnpm josh lane:prune`; `pnpm josh run:tidy`.
|
|
68
53
|
|
|
69
|
-
**The rewritten lock file reaches a pull request through the first lane.**
|
|
70
|
-
|
|
71
|
-
record it on
|
|
72
|
-
"backlogrun: josh latest before lanes"` pops it by message** — never a positional `stash pop
|
|
73
|
-
|
|
74
|
-
parent's, before the driver starts.
|
|
54
|
+
**The rewritten lock file reaches a pull request through the first lane.** Only if the update rewrote
|
|
55
|
+
anything: `git stash push -u -m "backlogrun: josh latest before lanes"` in the primary checkout, and
|
|
56
|
+
record it on the first child's Issue. **The first lane's `pnpm josh lane:launch "$n" --stash
|
|
57
|
+
"backlogrun: josh latest before lanes"` pops it by message** — never a positional `stash pop`. **Under
|
|
58
|
+
`backlog:drive` the driver passes `--stash`, never you**; the push stays the parent's.
|
|
75
59
|
|
|
76
60
|
### Opening one lane and dispatching its child
|
|
77
61
|
|
|
78
|
-
**One command opens the lane, prepares it, and dispatches the child — `pnpm josh lane:launch
|
|
79
|
-
`lane:open`, `stash:pop` and `lane:dispatch`, each guard unchanged; rationale:
|
|
80
|
-
`docs/maintainers/backlogrun-lanes-rationale.md` → "Why `lane:launch` folds the lane steps into one"):
|
|
62
|
+
**One command opens the lane, prepares it, and dispatches the child — `pnpm josh lane:launch`**:
|
|
81
63
|
|
|
82
64
|
```bash
|
|
83
65
|
pid=$(pnpm josh lane:launch "$n") || exit 1 # the child's pid on stdout, nothing else
|
|
@@ -85,98 +67,77 @@ pid=$(pnpm josh lane:launch "$n") || exit 1 # the child's pid on stdout, nothi
|
|
|
85
67
|
|
|
86
68
|
| It answers | What the run does |
|
|
87
69
|
| --- | --- |
|
|
88
|
-
| a pid | The child runs;
|
|
70
|
+
| a pid | The child runs; wait on it with `lane:await` |
|
|
89
71
|
| empty, non-zero, `full` | No free lane; wait for one |
|
|
90
72
|
| empty, non-zero, `already-open` or a failed install | **Park that child and name `pnpm josh lane:close <N>`** — a lock the lane cannot build is a person's to fix |
|
|
91
73
|
| `lane:open` reports a reused `<N>-lane` on stderr | The way back to a child parked after it pushed — **a reused branch is not a fresh lane** |
|
|
92
74
|
|
|
93
|
-
**Nothing switches the lane's branch.** In a lane `lane:open`'s answer replaces `pnpm josh
|
|
94
|
-
preflight
|
|
75
|
+
**Nothing switches the lane's branch.** In a lane, `lane:open`'s answer replaces `pnpm josh
|
|
76
|
+
run:hold`'s preflight; the child claims `run:hold` inside the lane.
|
|
95
77
|
|
|
96
78
|
### Handing the child over
|
|
97
79
|
|
|
98
|
-
The child runs as `fullrun #<N>` in that lane,
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
- **
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
**Start each child without blocking on it, and poll them all** — a silent one is
|
|
122
|
-
`backlogrun-recovery.md` → "A delegated unit that stopped without reporting", read in that child's
|
|
123
|
-
lane.
|
|
124
|
-
|
|
125
|
-
**`pnpm josh ms` is the parent's now, not the child's.** No lane can switch to the
|
|
126
|
-
default branch, so the refresh moves to the primary checkout **before each `lane:open`** — the ref the
|
|
127
|
-
lane is cut from.
|
|
80
|
+
The child runs as `fullrun #<N>` in that lane, with neither `josh latest` nor a progress watcher.
|
|
81
|
+
Everything else is unchanged; `pnpm josh followup` releases the lane's hold at the merge.
|
|
82
|
+
|
|
83
|
+
**The child is started as a process of its own, not as a subagent of this session** (`lane:dispatch`,
|
|
84
|
+
`lane:launch`'s final step):
|
|
85
|
+
|
|
86
|
+
- **It records where the child writes** — `<temp>/josh-lane-dispatch-<N>.log`.
|
|
87
|
+
- **A refusal is an empty capture beside a non-zero exit**, with a `warning` Telegram. **Park that
|
|
88
|
+
child and name the log the message carries**; never re-dispatch into the same lane without reading it.
|
|
89
|
+
- **A child that started with nowhere to write exits zero and warns** — **wait on that lane with
|
|
90
|
+
`lane:await`, which reads the process trace alone**.
|
|
91
|
+
- **The child is started as `fullrun #<N>` with the lane as its working directory**; the typed
|
|
92
|
+
`backlogrun` covers it.
|
|
93
|
+
- **It passes `--permission-mode bypassPermissions`, never `--dangerously-skip-permissions`.**
|
|
94
|
+
`.claude/settings.json`'s `deny` list still refuses what it names; report what stopped, never loosen it.
|
|
95
|
+
|
|
96
|
+
**Start each child without blocking on it, then wait on `backlog:drive` or `lane:await`**
|
|
97
|
+
(`scripts/run/run-poll-hook.ts`) — a silent one is
|
|
98
|
+
`backlogrun-recovery.md` → "A delegated unit that stopped without reporting", read in that child's lane.
|
|
99
|
+
|
|
100
|
+
**`pnpm josh ms` is the parent's now, not the child's** — run it in the primary checkout **before
|
|
101
|
+
each `lane:open`**.
|
|
128
102
|
|
|
129
103
|
### Conflicts are not predicted
|
|
130
104
|
|
|
131
105
|
**A child whose pull request conflicts with `main` resolves it in its own lane rather than stopping** —
|
|
132
|
-
read `backlogrun-recovery.md` → "Conflicts are not predicted" when `pnpm josh followup` reports
|
|
133
|
-
conflict.
|
|
106
|
+
read `backlogrun-recovery.md` → "Conflicts are not predicted" when `pnpm josh followup` reports it.
|
|
134
107
|
|
|
135
108
|
### What happens to a lane
|
|
136
109
|
|
|
137
110
|
| When | The lane | Why |
|
|
138
111
|
| --- | --- | --- |
|
|
139
|
-
| The child **merged** | `pnpm josh lane:close <N>` |
|
|
140
|
-
| The child was **parked before its commit** | **Left open**, its uncommitted work in place, its directory and held seat recorded on the Issue | The stash stack is
|
|
141
|
-
| The child was **parked after its commit and push** | **Left open**, its directory and held seat recorded on the Issue |
|
|
142
|
-
| The child hit a **merge conflict** | **Left open** — the resolution happens in it |
|
|
143
|
-
| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work
|
|
144
|
-
| The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count |
|
|
145
|
-
| **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child |
|
|
146
|
-
| The lane is **spent** — no child working in it, its Issue closed, not one this run launched and has not collected with `run:merge`, a clean tree, no commit that is on no remote | Nothing to do — `pnpm josh lane:prune` closes it |
|
|
147
|
-
| The run was **interrupted** | Nothing to do — the work tree survives on disk |
|
|
148
|
-
|
|
149
|
-
**A lane closed after a push is reopened by `pnpm josh lane:open <N
|
|
150
|
-
|
|
151
|
-
still has to have reached the remote for that to hold** — a child parked before its commit has nothing
|
|
152
|
-
on `origin`, which is why that row keeps its lane open rather than closing it. Rationale:
|
|
153
|
-
`docs/maintainers/backlogrun-lanes-rationale.md` → "Why a committed child's lane is kept".
|
|
112
|
+
| The child **merged** | `pnpm josh lane:close <N>` | Nothing in that tree is wanted |
|
|
113
|
+
| The child was **parked before its commit** | **Left open**, its uncommitted work in place, its directory and held seat recorded on the Issue | The shared stash stack is unsafe; `lane:close` is a **forced** removal. `pnpm josh lane:launch <N>` re-dispatches into the kept lane (a failed-install lane is still refused) |
|
|
114
|
+
| The child was **parked after its commit and push** | **Left open**, its directory and held seat recorded on the Issue | `lane:close` would take the **local branch**, the resume path |
|
|
115
|
+
| The child hit a **merge conflict** | **Left open** — the resolution happens in it | `backlogrun-recovery.md` → "Conflicts are not predicted"; a park there takes the row above |
|
|
116
|
+
| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work is what a person looks at. Name the lane directory in the stop report and Telegram |
|
|
117
|
+
| The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count | **A merge conflict is not this row**, and is not counted |
|
|
118
|
+
| **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child | Frees the seat; a person fixes the cause. Carry pnpm's reason into the park note |
|
|
119
|
+
| The lane is **spent** — no child working in it, its Issue closed, not one this run launched and has not collected with `run:merge`, a clean tree, no commit that is on no remote | Nothing to do — `pnpm josh lane:prune` closes it | Any other lane is kept, with the reason on standard error |
|
|
120
|
+
| The run was **interrupted** | Nothing to do — the work tree survives on disk | **Park that child**, naming the lane and `pnpm josh lane:close <N>` |
|
|
121
|
+
|
|
122
|
+
**A lane closed after a push is reopened by `pnpm josh lane:open <N>`** (a local `<N>-lane`, or one
|
|
123
|
+
from `origin/<N>-lane`). A child parked before its commit has nothing on `origin`, so its lane stays open.
|
|
154
124
|
|
|
155
125
|
**Which row a child takes is decided by what `followup` printed, not by reading the situation.** **What
|
|
156
|
-
it prints is `PR checks failed (merge conflict)`** —
|
|
157
|
-
`mergeStateStatus: DIRTY`
|
|
158
|
-
output line to search for. That string sends the child to resolve the conflict in the lane it is
|
|
159
|
-
standing in. Do not grep the output for `mergeable_state`: that is the REST field name, normalized away
|
|
160
|
-
before anything prints it.
|
|
126
|
+
it prints is `PR checks failed (merge conflict)`** — resolve in the lane. Never search for
|
|
127
|
+
`mergeStateStatus: DIRTY` or `mergeable_state`; neither is printed.
|
|
161
128
|
|
|
162
129
|
**A kept lane holds its seat. Say it in the park comment**: the lane directory, that its seat is held,
|
|
163
|
-
and `pnpm josh lane:close <N>`
|
|
130
|
+
and `pnpm josh lane:close <N>` to give it back.
|
|
164
131
|
|
|
165
|
-
**Release the hold on either parked arm, and leave the lane before closing it
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
`lane:close` does not release the hold for you — the record is keyed to the work tree's git directory,
|
|
170
|
-
so removing the tree strands it. And `cd` out of the lane **before** `pnpm josh lane:close <N>`: the
|
|
171
|
-
close removes the directory the shell is sitting in.
|
|
132
|
+
**Release the hold on either parked arm, and leave the lane before closing it**: `pnpm josh
|
|
133
|
+
run:release <N>` in the lane (**a release names the run it belongs to**); `lane:close` does not
|
|
134
|
+
release it. `cd` out of the lane **before** `pnpm josh lane:close <N>`. **A `needs-human-review` stop is
|
|
135
|
+
not a park and keeps its hold.**
|
|
172
136
|
|
|
173
|
-
**A `needs-human-review` stop ends the run, and the lanes already in flight are allowed to finish
|
|
174
|
-
new lane
|
|
175
|
-
stop.
|
|
137
|
+
**A `needs-human-review` stop ends the run, and the lanes already in flight are allowed to finish** —
|
|
138
|
+
no new lane opens, no unit is killed mid-gate; then report and stop.
|
|
176
139
|
|
|
177
140
|
### CI concurrency
|
|
178
141
|
|
|
179
|
-
**`JOSH_LANE_LIMIT` lowers the ceiling with no code** when CI jobs
|
|
180
|
-
|
|
181
|
-
is the queueing. Rationale: `docs/maintainers/backlogrun-lanes-rationale.md` → "Why CI concurrency is
|
|
182
|
-
capped by the lane limit".
|
|
142
|
+
**`JOSH_LANE_LIMIT` lowers the ceiling with no code** when CI jobs queue — a `checks-wait` growing
|
|
143
|
+
with the lane count in the backlog timing report.
|