@plot-pm/board 0.18.0 → 0.19.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/dist/board-server.mjs +214 -207
- package/package.json +2 -1
- package/plot-approve.sh +9 -978
- package/plot-config.sh +8 -0
- package/plot-fleet-scan.sh +2 -2
- package/plot-host.sh +194 -110
- package/plot-reap.sh +12 -1250
package/plot-approve.sh
CHANGED
|
@@ -1,981 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env bash
|
|
2
|
-
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
5
|
-
# --who the name recorded in the `Approved:` line (default: git user.name)
|
|
6
|
-
# <slug> the plan to approve
|
|
7
|
-
# Output: one `step:` line per step, then a machine-countable summary:
|
|
8
|
-
# summary: merged=yes phase=flipped record=written holds=1 sprint=none push=clean
|
|
9
|
-
# Exit 0 when the plan is Approved on the default branch (whether this
|
|
10
|
-
# run did the work or found it already done); 1 on a refusal or a
|
|
11
|
-
# failure, with the reason on stderr.
|
|
12
|
-
#
|
|
13
|
-
# WHY THIS EXISTS. `Start work` on the board calls plot-dispatch.sh, a script
|
|
14
|
-
# Plot ships, and works out of the box. `Approve` beside it called
|
|
15
|
-
# `sh -c '<Approve command> ...'` and did not, because no such script existed —
|
|
16
|
-
# so the board reached for an agent, and the button rendered dimmed on every
|
|
17
|
-
# card in a repo that declares no `Approve command`.
|
|
18
|
-
#
|
|
19
|
-
# The justification for the asymmetry did not survive the comparison.
|
|
20
|
-
# `Worker command` is per-project because dispatch starts an agent that WRITES
|
|
21
|
-
# AN IMPLEMENTATION — genuinely unknowable to Plot (Principle 5). Approving,
|
|
22
|
-
# under `Review: pr`, is seven writes with no judgement in any of them:
|
|
23
|
-
# read the ceremony answers and the PR state, merge the plan PR, flip the
|
|
24
|
-
# phase, fill the `Approved:` record, clear the `.plot/hold` entries, update
|
|
25
|
-
# the sprint annotation, push. Every one is gh, git, or one line into a
|
|
26
|
-
# markdown file. Approving writes one line; dispatching starts a program that
|
|
27
|
-
# writes a codebase.
|
|
28
|
-
#
|
|
29
|
-
# Manifesto Principle 3 draws the line where this problem is: SCRIPTS COLLECT
|
|
30
|
-
# AND REPORT; SKILLS INTERPRET AND ADAPT. Merging a PR whose number the plan
|
|
31
|
-
# already records, and writing a dated line into a known field, is collecting.
|
|
32
|
-
# Deciding whether a plan is READY is interpreting, and stays in the skill —
|
|
33
|
-
# along with the in-session walkthrough, the ballot tally, the two ceremony
|
|
34
|
-
# questions, and the tracer-bullet suggestion.
|
|
35
|
-
#
|
|
36
|
-
# SEVEN STEPS, NOT FIVE. The hold and the sprint annotation are here because
|
|
37
|
-
# they are writes with no decision in them, and because leaving either to a
|
|
38
|
-
# caller re-creates the split this script exists to close. An approval that
|
|
39
|
-
# leaves the hold in place STILL BLOCKS commits; one that skips the annotation
|
|
40
|
-
# makes `/plot-sprint status` wrong. Five of seven steps would be a
|
|
41
|
-
# half-approval, which is worse than none.
|
|
42
|
-
#
|
|
43
|
-
# IT IS IDEMPOTENT, BECAUSE ONE STEP CANNOT BE UNDONE. Step 2 merges the PR and
|
|
44
|
-
# that write is irreversible; everything after it is local. A run interrupted
|
|
45
|
-
# between the merge and the push leaves the PR merged while the plan on the
|
|
46
|
-
# default branch still reads `Phase: Draft` — the exact state the skill names as
|
|
47
|
-
# the thing never to allow. So `plot-approve.sh <slug>` may run any number of
|
|
48
|
-
# times, and RUN IT AGAIN is the repair for every interruption.
|
|
49
|
-
#
|
|
50
|
-
# Each step asks THE SOURCE IT WOULD HAVE WRITTEN whether it is already done:
|
|
51
|
-
# pr-state for the merge, plot-plan-meta.sh for the phase and the record, the
|
|
52
|
-
# hold file for the holds, the sprint file for the annotation. Never a progress
|
|
53
|
-
# file of its own — that would be a second source of truth, free to disagree
|
|
54
|
-
# with the repository exactly when a human intervened by hand between two runs,
|
|
55
|
-
# which is the case it would exist for. Git and the files ARE the state
|
|
56
|
-
# (Principle 1).
|
|
57
|
-
#
|
|
58
|
-
# Reordering to put the merge LAST was the alternative and it is worse: it
|
|
59
|
-
# would leave a window where the plan reads `Approved` while its PR is still
|
|
60
|
-
# open, and where the `Approved:` record names a PR number that never merged —
|
|
61
|
-
# trading a recoverable half-state for a lying one.
|
|
62
|
-
#
|
|
63
|
-
# IT SURVIVES ITS OWN REPO'S GATE. plot-phase-gate.sh is a PreToolUse hook that
|
|
64
|
-
# blocks implementation commits while the governing plan is Draft — and this
|
|
65
|
-
# script commits exactly then, because rewriting the phase IS the transition.
|
|
66
|
-
# The gate lets plan-file-only commits through (`outside_plans` returns false
|
|
67
|
-
# when every effective path is under the plan directory), which is why this
|
|
68
|
-
# script stages ONLY the plan file and the two bookkeeping files, and never
|
|
69
|
-
# `git add -A`. That is not a nicety: an -A here would stage whatever else the
|
|
70
|
-
# booking worktree happened to hold and hand the gate a reason to block.
|
|
71
|
-
#
|
|
72
|
-
# THE HOLD IS KEYED BY BRANCH, NOT BY PLAN. plot-phase-gate.sh:121 matches
|
|
73
|
-
# `$1 == b` against the branch NAME, and a plan names several branches. So this
|
|
74
|
-
# reads the plan's `## Branches` section and removes the entry for each — the
|
|
75
|
-
# plan is what connects a slug to the branch names the hold file speaks in.
|
|
76
|
-
# Entries for branches this plan does not name stay exactly where they are:
|
|
77
|
-
# approving one piece of work must not release someone else's gate. There is no
|
|
78
|
-
# `.plot/hold` in this repo at all, so the ABSENT path is the common one and is
|
|
79
|
-
# never an error.
|
|
80
|
-
#
|
|
81
|
-
# WHAT IT REFUSES, and why refusing beats guessing:
|
|
82
|
-
# - phase is not `draft` or `design` — nothing to approve. (Design is the
|
|
83
|
-
# transitional phase before Approved; approving it is its forward exit.)
|
|
84
|
-
# - `Review:` is not `pr` — `in-session` and `ballot` need a human in the
|
|
85
|
-
# room. Every plan in this repo declares `Review: pr`, so this fires for
|
|
86
|
-
# nothing today and is still load-bearing: /plot-idea offers all three, and
|
|
87
|
-
# a script treating an unfamiliar `Review:` as `pr` would approve a plan
|
|
88
|
-
# nobody discussed, silently, with a commit indistinguishable from a
|
|
89
|
-
# legitimate one.
|
|
90
|
-
# - the PR is draft, closed, or absent — the skill's preconditions, moved
|
|
91
|
-
# from prose into an exit code.
|
|
92
|
-
# Refusing is this script's job; EXPLAINING is its output. The board surfaces a
|
|
93
|
-
# failing command's own words on the card, so a refusal reaches the reader
|
|
94
|
-
# without the board learning any of these rules.
|
|
95
|
-
#
|
|
96
|
-
# macOS bash 3.2 throughout: no associative arrays, no bash-4 line readers.
|
|
97
|
-
# (Named literally, the repo's own bash-3.2 lint would flag this comment.)
|
|
2
|
+
# Launcher. The mechanical half of approving a plan is `board/plot-approve.mjs`,
|
|
3
|
+
# a JS entry point over the domain — see its header for what it does. This
|
|
4
|
+
# resolves it, passes arguments and the exit code through, and decides nothing.
|
|
98
5
|
set -uo pipefail
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
# other writer of a `State:` line. Sourced rather than run: the gate and the
|
|
105
|
-
# three owning scripts must agree on where a receipt lives, and one file is how.
|
|
106
|
-
# shellcheck source=plot-state-receipt.sh
|
|
107
|
-
. "$script_dir/plot-state-receipt.sh"
|
|
108
|
-
|
|
109
|
-
dry_run=0
|
|
110
|
-
who_flag_given=0
|
|
111
|
-
who_flag=""
|
|
112
|
-
slug=""
|
|
113
|
-
while [ $# -gt 0 ]; do
|
|
114
|
-
case "$1" in
|
|
115
|
-
--dry-run) dry_run=1 ;;
|
|
116
|
-
--who) who_flag_given=1; who_flag="${2:-}"; shift ;;
|
|
117
|
-
-h|--help) sed -n '2,12p' "$0"; exit 0 ;;
|
|
118
|
-
-*) echo "plot-approve: unknown flag '$1'" >&2; exit 1 ;;
|
|
119
|
-
*) slug="$1" ;;
|
|
120
|
-
esac
|
|
121
|
-
shift
|
|
122
|
-
done
|
|
123
|
-
|
|
124
|
-
die() { echo "plot-approve: $*" >&2; exit 1; }
|
|
125
|
-
|
|
126
|
-
[ -n "$slug" ] || die "need a plan slug (usage: plot-approve.sh [--dry-run] <slug>)"
|
|
127
|
-
git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run this from inside the checkout, or 'git init' one here"
|
|
128
|
-
|
|
129
|
-
cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
|
|
130
|
-
|
|
131
|
-
repo_root=$(git rev-parse --show-toplevel)
|
|
132
|
-
# The booking worktree goes under the desk root of the MAIN checkout, never of
|
|
133
|
-
# this tree: inside a desk `--show-toplevel` answers the desk, and the default
|
|
134
|
-
# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
|
|
135
|
-
# shellcheck source=plot-desk-root.sh
|
|
136
|
-
. "$script_dir/plot-desk-root.sh"
|
|
137
|
-
main_root=$(plot_repo_root)
|
|
138
|
-
wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
|
|
139
|
-
|
|
140
|
-
PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
|
|
141
|
-
ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
|
|
142
|
-
SPRINT_DIR=$(cfg "Sprint directory" "docs/sprints/")
|
|
143
|
-
|
|
144
|
-
# ---------------------------------------------------------------------------
|
|
145
|
-
# Step 1 — read the plan's ceremony answers and the PR state
|
|
146
|
-
# ---------------------------------------------------------------------------
|
|
147
|
-
|
|
148
|
-
plan_file=""
|
|
149
|
-
for cand in "$ACTIVE_DIR$slug.md" "$PLAN_DIR"*"$slug".md; do
|
|
150
|
-
[ -e "$cand" ] && { plan_file="$cand"; break; }
|
|
151
|
-
done
|
|
152
|
-
[ -n "$plan_file" ] || die "no plan found for '$slug' — looked in $ACTIVE_DIR and $PLAN_DIR.
|
|
153
|
-
Check the slug: ls $PLAN_DIR | grep -i '$slug'
|
|
154
|
-
Or create the plan first: /plot-idea"
|
|
155
|
-
|
|
156
|
-
meta=$(bash "$script_dir/plot-plan-meta.sh" "$plan_file" 2>/dev/null) || meta=""
|
|
157
|
-
[ -n "$meta" ] || die "cannot parse '$plan_file' — refusing rather than guessing.
|
|
158
|
-
See what the parser reads: $script_dir/plot-plan-meta.sh $plan_file
|
|
159
|
-
A plan needs a '## Status' section with a 'State:' field."
|
|
160
|
-
|
|
161
|
-
jfield() { printf '%s' "$meta" | jq -r "$1" 2>/dev/null; }
|
|
162
|
-
|
|
163
|
-
phase=$(jfield '.phase')
|
|
164
|
-
review=$(jfield '.review')
|
|
165
|
-
impl=$(jfield '.impl')
|
|
166
|
-
sprint=$(jfield '.sprint')
|
|
167
|
-
approved_raw=$(jfield '.approved_raw')
|
|
168
|
-
|
|
169
|
-
# The plan's branches, one per line. This is what the hold file is keyed by.
|
|
170
|
-
plan_branches=$(jfield '.branches[]?')
|
|
171
|
-
|
|
172
|
-
# --- refusal 1: the phase ---------------------------------------------------
|
|
173
|
-
#
|
|
174
|
-
# `draft` and `design` both approve: Design is the transitional phase before
|
|
175
|
-
# Approved — a spike or tracer bullet that answered its question — and approving
|
|
176
|
-
# it is the forward exit the plan gives it. `approved` is NOT a refusal either:
|
|
177
|
-
# it is the idempotent case. A run that finds the phase already flipped still
|
|
178
|
-
# has holds to clear, an annotation to check, and a record that may be missing —
|
|
179
|
-
# the very half-states this script exists to repair. Only phases with nothing to
|
|
180
|
-
# approve are refused.
|
|
181
|
-
case "$phase" in
|
|
182
|
-
draft|design|approved) ;;
|
|
183
|
-
delivered|released)
|
|
184
|
-
die "plan '$slug' is already $phase — nothing to approve.
|
|
185
|
-
Nothing to do here. To take the work further: /plot-release" ;;
|
|
186
|
-
NONE|"")
|
|
187
|
-
die "cannot read the phase of '$slug' ($plan_file) — refusing rather than guessing.
|
|
188
|
-
Its '## Status' section needs a line reading '- **State:** Draft'." ;;
|
|
189
|
-
*)
|
|
190
|
-
die "plan '$slug' is in phase '$phase' — only a Draft or Design plan can be approved.
|
|
191
|
-
If that phase is wrong, correct the 'State:' line in $plan_file and push it." ;;
|
|
192
|
-
esac
|
|
193
|
-
|
|
194
|
-
# --- refusal 2: the review channel ------------------------------------------
|
|
195
|
-
#
|
|
196
|
-
# NONE means a pre-Plot-2 plan on an idea branch, which the skill documents as
|
|
197
|
-
# `pr` by default. An unrecognised value is refused rather than defaulted:
|
|
198
|
-
# "carry on" is the shape of stale assumption this whole story keeps finding.
|
|
199
|
-
#
|
|
200
|
-
# `in-session` IS NO LONGER A REFUSAL HERE, which is this slice's whole change.
|
|
201
|
-
# `plot-approve.sh --who <handle> <slug>` performs the seven mechanical steps
|
|
202
|
-
# for it exactly as it does for `pr`, because #1185 made the domain able to
|
|
203
|
-
# decide the write (`approveTransition` takes `who` and `people`). What stays a
|
|
204
|
-
# refusal is the absence of a usable reviewer: no `--who` at all, an empty one,
|
|
205
|
-
# or one `People` does not declare — the domain's `review-human` and
|
|
206
|
-
# `reviewer-undeclared` gates, asked through `decide_transition` below rather
|
|
207
|
-
# than re-implemented here. There is no `--reviewer`: a round-1 panel measured
|
|
208
|
-
# that spelling exiting 2 at the controller gate, and `--who` is the one flag
|
|
209
|
-
# this script already declares.
|
|
210
|
-
#
|
|
211
|
-
# UNDER `PLOT_UNATTENDED=1` THIS STILL REFUSES, `--who` or not. The reviewer is
|
|
212
|
-
# a human in a session that, by definition, has nobody in it under an
|
|
213
|
-
# unattended run — the same argument `plot-approve/SKILL.md` already makes for
|
|
214
|
-
# the skill's own in-session walkthrough. A default here would let the machine
|
|
215
|
-
# name the reviewer, which is exactly what `--who`'s absence of a fallback (no
|
|
216
|
-
# `PLOT_APPROVE_WHO`, no `git config user.name`) refuses for the same channel.
|
|
217
|
-
in_session=0
|
|
218
|
-
case "$review" in
|
|
219
|
-
pr|NONE) ;;
|
|
220
|
-
in-session)
|
|
221
|
-
if [ "${PLOT_UNATTENDED:-}" = "1" ]; then
|
|
222
|
-
die "plan '$slug' declares 'Review: in-session' — the reviewer is a human in the room.
|
|
223
|
-
Refusing under PLOT_UNATTENDED=1: there is nobody here to name. Approve it from a session: /plot-approve $slug"
|
|
224
|
-
fi
|
|
225
|
-
# No reviewer named: refuse before any git work. The domain's `review-human`
|
|
226
|
-
# gate says the same thing later, after a booking worktree exists; asking
|
|
227
|
-
# here keeps a refusal local and cheap. `--who` has no default.
|
|
228
|
-
if [ -z "$(printf '%s' "$who_flag" | tr -d '[:space:]')" ]; then
|
|
229
|
-
die "plan '$slug' declares 'Review: in-session' — name the reviewer with --who."
|
|
230
|
-
fi
|
|
231
|
-
in_session=1
|
|
232
|
-
;;
|
|
233
|
-
ballot)
|
|
234
|
-
die "plan '$slug' declares 'Review: ballot' — the tally is the approval.
|
|
235
|
-
A script cannot read a ballot. Approve it with /plot-approve $slug." ;;
|
|
236
|
-
*)
|
|
237
|
-
die "plan '$slug' records an unrecognised 'Review:' answer ('$review').
|
|
238
|
-
Refusing rather than treating it as 'pr' — that would approve a plan nobody discussed." ;;
|
|
239
|
-
esac
|
|
240
|
-
|
|
241
|
-
# The declared handles, for the domain's `reviewer-undeclared` gate. Read
|
|
242
|
-
# unconditionally — cheap, and a `pr` or `ballot` plan never reaches the branch
|
|
243
|
-
# that uses it — from `People`'s `handle = Spelling; handle = Spelling` form:
|
|
244
|
-
# only the text before each `=` is a handle, and `People` may be absent.
|
|
245
|
-
people_raw=$(cfg "People" "")
|
|
246
|
-
people_csv=$(printf '%s' "$people_raw" | tr ';' '\n' | while IFS= read -r entry; do
|
|
247
|
-
h="${entry%%=*}"
|
|
248
|
-
h="$(printf '%s' "$h" | sed -e 's/^[ \t]*//' -e 's/[ \t]*$//' | tr '[:upper:]' '[:lower:]')"
|
|
249
|
-
[ -n "$h" ] && printf '%s\n' "$h"
|
|
250
|
-
done | paste -sd, -)
|
|
251
|
-
[ -n "$people_csv" ] || people_csv=""
|
|
252
|
-
|
|
253
|
-
# Read even for in-session: the booking worktree below (every non-same-branch
|
|
254
|
-
# flow, in-session included) fetches and books against it.
|
|
255
|
-
MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
|
|
256
|
-
[ -n "$MAIN" ] || MAIN=$(bash "$script_dir/plot-host.sh" default-branch 2>/dev/null) || MAIN=""
|
|
257
|
-
[ -n "$MAIN" ] || MAIN="main"
|
|
258
|
-
|
|
259
|
-
if [ "$in_session" = 1 ]; then
|
|
260
|
-
# No plan PR to read or merge: the approval IS the reviewer's go, not a host
|
|
261
|
-
# state. `same_branch` stays 0 — in-session records through the same booking
|
|
262
|
-
# worktree the `pr` flow uses, since an in-session plan has no work branch of
|
|
263
|
-
# its own to record on.
|
|
264
|
-
same_branch=0
|
|
265
|
-
pr_number=0
|
|
266
|
-
pr_state="NONE"
|
|
267
|
-
pr_draft="false"
|
|
268
|
-
echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} (in-session, no plan PR)"
|
|
269
|
-
else
|
|
270
|
-
# The PR that carries the plan. `Impl: same branch` puts plan and code on the
|
|
271
|
-
# work branch, so its PR is the WORK branch's — and it must not be merged here
|
|
272
|
-
# (it merges once, at the end, carrying the implementation with it).
|
|
273
|
-
same_branch=0
|
|
274
|
-
[ "$impl" = "same-branch" ] && same_branch=1
|
|
275
|
-
|
|
276
|
-
if [ "$same_branch" = 1 ]; then
|
|
277
|
-
pr_branch="$slug"
|
|
278
|
-
for p in $(cfg "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" | tr ',' ' '); do
|
|
279
|
-
p="${p%/}"; p="${p# }"
|
|
280
|
-
[ -z "$p" ] && continue
|
|
281
|
-
[ "$p" = "idea" ] && continue
|
|
282
|
-
if git show-ref --verify --quiet "refs/heads/$p/$slug" \
|
|
283
|
-
|| git show-ref --verify --quiet "refs/remotes/origin/$p/$slug"; then
|
|
284
|
-
pr_branch="$p/$slug"
|
|
285
|
-
break
|
|
286
|
-
fi
|
|
287
|
-
done
|
|
288
|
-
else
|
|
289
|
-
pr_branch="idea/$slug"
|
|
290
|
-
fi
|
|
291
|
-
|
|
292
|
-
# THE EXIT CODE IS THE READING, not the emptiness of stdout. `pr-state` exits 0
|
|
293
|
-
# with `state: NONE` when the host answered that the branch has no PR, and
|
|
294
|
-
# non-zero when the host could not be asked: 3 for a refused or failed call
|
|
295
|
-
# (a rate limit included), 4 for a backend with no answer at all. Only the
|
|
296
|
-
# first is an absence. The other two stop here with the host's own words and
|
|
297
|
-
# name no repair to the branch, because nothing about the branch was read.
|
|
298
|
-
pr_err_file=""
|
|
299
|
-
plot_tmpfile pr_err_file approve-pr
|
|
300
|
-
pr_rc=0
|
|
301
|
-
pr_json=$(bash "$script_dir/plot-host.sh" pr-state "$pr_branch" 2>"$pr_err_file") || pr_rc=$?
|
|
302
|
-
pr_err=$(cat "$pr_err_file" 2>/dev/null); rm -f "$pr_err_file"
|
|
303
|
-
if [ "$pr_rc" = 4 ]; then
|
|
304
|
-
die "the host backend has no answer for the PR state of '$pr_branch' (plot-host.sh pr-state exited 4).
|
|
305
|
-
${pr_err:-The host adapter gave no reason.}
|
|
306
|
-
This backend cannot report a PR's state, so the approval cannot read its gate. The plan was not approved and its phase is unchanged."
|
|
307
|
-
elif [ "$pr_rc" != 0 ]; then
|
|
308
|
-
die "the host could not be asked for the PR of '$pr_branch' (plot-host.sh pr-state exited $pr_rc).
|
|
309
|
-
${pr_err:-The host adapter gave no reason.}
|
|
310
|
-
The plan was not approved and its phase is unchanged. Wait for the host to answer again, then re-run the approval."
|
|
311
|
-
fi
|
|
312
|
-
[ -n "$pr_json" ] || pr_json='{"number":0,"state":"NONE","draft":false,"url":""}'
|
|
313
|
-
pr_number=$(printf '%s' "$pr_json" | jq -r '.number // 0' 2>/dev/null)
|
|
314
|
-
pr_state=$(printf '%s' "$pr_json" | jq -r '.state // "NONE"' 2>/dev/null)
|
|
315
|
-
pr_draft=$(printf '%s' "$pr_json" | jq -r '.draft // false' 2>/dev/null)
|
|
316
|
-
|
|
317
|
-
# --- refusal 3: the PR ------------------------------------------------------
|
|
318
|
-
case "$pr_state" in
|
|
319
|
-
MERGED) ;;
|
|
320
|
-
OPEN) ;;
|
|
321
|
-
CLOSED)
|
|
322
|
-
die "the plan PR for '$slug' (#$pr_number) is closed.
|
|
323
|
-
Reopen it on the host, or push '$pr_branch' again and open a new one." ;;
|
|
324
|
-
NONE|*)
|
|
325
|
-
die "no PR found for branch '$pr_branch'.
|
|
326
|
-
Push the branch: git push -u origin $pr_branch
|
|
327
|
-
Then open its PR — or run /plot-idea, which does both." ;;
|
|
328
|
-
esac
|
|
329
|
-
fi
|
|
330
|
-
|
|
331
|
-
# --- refusal 4: a branch under no slice heading -----------------------------
|
|
332
|
-
#
|
|
333
|
-
# BEFORE THE MERGE, which is the whole point of its position. Step 2 merges the
|
|
334
|
-
# plan PR, and a refusal fired after that leaves the PR merged, the plan still
|
|
335
|
-
# Draft, and a refusal the operator can clear only by editing a merged plan. So
|
|
336
|
-
# it sits with refusals 1 to 3, reading the same `$meta` step 1 took, and it
|
|
337
|
-
# writes nothing.
|
|
338
|
-
#
|
|
339
|
-
# The heading is the slice's name on the board and the title of its PR
|
|
340
|
-
# (`openSlicePr` refuses `slice-unnamed`), so it is owed on the default branch
|
|
341
|
-
# before any agent starts. Without this an agent meets that refusal, writes the
|
|
342
|
-
# heading on its own branch, and the board reads `(unnamed)` until the PR
|
|
343
|
-
# merges (#1057).
|
|
344
|
-
#
|
|
345
|
-
# The rule is the domain's and it is asked, never re-implemented here:
|
|
346
|
-
# `decide_transition` asks the same one through the same bundle, so the two can
|
|
347
|
-
# never disagree about one plan.
|
|
348
|
-
transition_check_mjs="$script_dir/board/plot-transition.mjs"
|
|
349
|
-
if [ -f "$transition_check_mjs" ]; then
|
|
350
|
-
slice_err_file=""
|
|
351
|
-
plot_tmpfile slice_err_file approve-slices
|
|
352
|
-
slice_rc=0
|
|
353
|
-
printf '%s' "$meta" | node "$transition_check_mjs" --check-slices "$slug" \
|
|
354
|
-
2>"$slice_err_file" >/dev/null || slice_rc=$?
|
|
355
|
-
slice_err=$(cat "$slice_err_file" 2>/dev/null); rm -f "$slice_err_file"
|
|
356
|
-
if [ "$slice_rc" = 1 ]; then
|
|
357
|
-
die "$(printf '%s' "$slice_err" | cut -f2-)
|
|
358
|
-
The plan was not approved, nothing was merged and its phase is unchanged."
|
|
359
|
-
elif [ "$slice_rc" != 0 ]; then
|
|
360
|
-
die "cannot read the slices of '$plan_file' (plot-transition.mjs --check-slices exited $slice_rc).
|
|
361
|
-
${slice_err:-The bundle gave no reason.}
|
|
362
|
-
Refusing rather than approving a plan whose slice headings were never read."
|
|
363
|
-
fi
|
|
364
|
-
else
|
|
365
|
-
echo "plot-approve: cannot find $transition_check_mjs — slice headings went unchecked. Run 'pnpm build:board'." >&2
|
|
366
|
-
fi
|
|
367
|
-
|
|
368
|
-
[ "$in_session" = 1 ] || echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} pr=#$pr_number($pr_state)"
|
|
369
|
-
|
|
370
|
-
# --- a DRAFT is taken out of draft, not refused ------------------------------
|
|
371
|
-
#
|
|
372
|
-
# This refused until 2026-08-22 — *"still a draft PR. Mark it ready for review
|
|
373
|
-
# first"* — on the argument the skill states: the approval IS the PR's non-draft
|
|
374
|
-
# state, so approving a draft would approve something declaring itself unfinished.
|
|
375
|
-
#
|
|
376
|
-
# The argument holds between two people and costs the author a detour: they
|
|
377
|
-
# opened the plan, read it, and the one control that should conclude that is
|
|
378
|
-
# refusing. So the gate is not removed, it is PASSED BY THE SAME ACT: taking the
|
|
379
|
-
# PR out of draft is the first half of approving it, and the click that approves
|
|
380
|
-
# is the reader saying they have read.
|
|
381
|
-
#
|
|
382
|
-
# Ordered ready-then-merge because the reverse cannot exist — a draft PR is not
|
|
383
|
-
# mergeable on either host — and stated as its own `step:` line so a caller
|
|
384
|
-
# reading the output can see which half happened if the second one fails.
|
|
385
|
-
|
|
386
|
-
# `in-session` TAKES NO DEFAULT. A default here would let the machine name the
|
|
387
|
-
# reviewer, which is the one thing a script must never do for a channel that
|
|
388
|
-
# exists because a human is in the room — so `--who` alone answers, and an
|
|
389
|
-
# empty or absent one reaches the domain's `review-human` refusal below rather
|
|
390
|
-
# than silently becoming `git config user.name`. `pr` and the direct/same-branch
|
|
391
|
-
# flow keep the existing chain: `PLOT_APPROVE_WHO`, then the git identity.
|
|
392
|
-
if [ "$in_session" = 1 ]; then
|
|
393
|
-
who="$who_flag"
|
|
394
|
-
channel="in-session"
|
|
395
|
-
else
|
|
396
|
-
who="${who_flag:-${PLOT_APPROVE_WHO:-$(git config user.name 2>/dev/null || echo plot)}}"
|
|
397
|
-
fi
|
|
398
|
-
today=$(date +%Y-%m-%d)
|
|
399
|
-
|
|
400
|
-
if [ "$dry_run" = 1 ]; then
|
|
401
|
-
if [ "$in_session" = 1 ]; then
|
|
402
|
-
echo "step: would flip Phase → Approved and fill Approved: $today, $who, in-session"
|
|
403
|
-
echo "step: would clear .plot/hold entries for: $(printf '%s' "$plan_branches" | tr '\n' ' ')"
|
|
404
|
-
echo "step: would update the sprint annotation${sprint:+ in $SPRINT_DIR (sprint $sprint)}"
|
|
405
|
-
echo "step: would append a row to .plot/state/in-session-approvals.tsv"
|
|
406
|
-
echo "summary: merged=skipped-in-session phase=would record=would holds=would sprint=would push=would"
|
|
407
|
-
else
|
|
408
|
-
[ "$pr_draft" = "true" ] && echo "step: would mark PR #$pr_number ready for review"
|
|
409
|
-
echo "step: would merge PR #$pr_number"
|
|
410
|
-
echo "step: would flip Phase → Approved and fill Approved: $today, $who, plan-PR #$pr_number merged"
|
|
411
|
-
echo "step: would clear .plot/hold entries for: $(printf '%s' "$plan_branches" | tr '\n' ' ')"
|
|
412
|
-
echo "step: would update the sprint annotation${sprint:+ in $SPRINT_DIR (sprint $sprint)}"
|
|
413
|
-
echo "summary: merged=would phase=would record=would holds=would sprint=would push=would"
|
|
414
|
-
fi
|
|
415
|
-
exit 0
|
|
416
|
-
fi
|
|
417
|
-
|
|
418
|
-
# ---------------------------------------------------------------------------
|
|
419
|
-
# Step 2 — merge the plan PR. THE ONE IRREVERSIBLE WRITE.
|
|
420
|
-
# ---------------------------------------------------------------------------
|
|
421
|
-
#
|
|
422
|
-
# Already-done test: pr-state reports MERGED. That is the source this step
|
|
423
|
-
# would have written, asked directly.
|
|
424
|
-
#
|
|
425
|
-
# Merge commits, not squash: plan refinement history is the context a later
|
|
426
|
-
# reader wants. `--delete-branch` retires idea/<slug>, which has no further job.
|
|
427
|
-
merged_report="already"
|
|
428
|
-
if [ "$in_session" = 1 ]; then
|
|
429
|
-
# No plan PR exists for this channel: the approval is the reviewer's go,
|
|
430
|
-
# read nowhere on a host.
|
|
431
|
-
merged_report="skipped-in-session"
|
|
432
|
-
elif [ "$same_branch" = 1 ]; then
|
|
433
|
-
# Plan and code ride one branch; the PR merges once, at the end, and merging
|
|
434
|
-
# it here would land an unfinished implementation on the default branch.
|
|
435
|
-
merged_report="skipped-same-branch"
|
|
436
|
-
echo "step: merge skipped — 'Impl: same branch' keeps PR #$pr_number open for the implementation"
|
|
437
|
-
elif [ "$pr_state" = "MERGED" ]; then
|
|
438
|
-
echo "step: PR #$pr_number is already merged — the approval already happened"
|
|
439
|
-
else
|
|
440
|
-
# OUT OF DRAFT FIRST, where it is one — see the note above refusal 3. Its own
|
|
441
|
-
# step line, and its own refusal: a `pr-ready` that fails must not be read as
|
|
442
|
-
# a merge that failed, because the repairs differ (a permission or a CLI too
|
|
443
|
-
# old, against a conflict or a branch protection).
|
|
444
|
-
#
|
|
445
|
-
# Nothing is written before this point, so dying here leaves the estate
|
|
446
|
-
# exactly as it was found — the same property the merge failure below relies
|
|
447
|
-
# on, and the reason both refusals say so in the same words.
|
|
448
|
-
if [ "$pr_draft" = "true" ]; then
|
|
449
|
-
if bash "$script_dir/plot-host.sh" pr-ready "$pr_number" >/dev/null 2>&1; then
|
|
450
|
-
echo "step: marked PR #$pr_number ready for review"
|
|
451
|
-
else
|
|
452
|
-
die "could not take PR #$pr_number out of draft. Nothing else was written; mark it ready on the host and re-run."
|
|
453
|
-
fi
|
|
454
|
-
fi
|
|
455
|
-
if bash "$script_dir/plot-host.sh" pr-merge "$pr_number" --delete-branch >/dev/null 2>&1; then
|
|
456
|
-
merged_report="yes"
|
|
457
|
-
echo "step: merged PR #$pr_number"
|
|
458
|
-
else
|
|
459
|
-
die "could not merge PR #$pr_number. Nothing else was written; re-run once the merge works."
|
|
460
|
-
fi
|
|
461
|
-
fi
|
|
462
|
-
|
|
463
|
-
# ---------------------------------------------------------------------------
|
|
464
|
-
# Steps 3-6 — the local writes, all in one booking worktree off origin/<default>
|
|
465
|
-
# ---------------------------------------------------------------------------
|
|
466
|
-
#
|
|
467
|
-
# A SEPARATE WORKTREE, not a checkout here. The caller's working tree may carry
|
|
468
|
-
# uncommitted work, and switching it out from under them to record a note is
|
|
469
|
-
# exactly the write this script otherwise refuses. plot-dispatch.sh books the
|
|
470
|
-
# same way and for the same reason.
|
|
471
|
-
#
|
|
472
|
-
# `same branch` and the direct flow are the exceptions: their plan lives on the
|
|
473
|
-
# current branch, where it is already checked out, and the record belongs there.
|
|
474
|
-
|
|
475
|
-
# The CANONICAL plan file, not the index symlink: a later active/ → delivered/
|
|
476
|
-
# move would carry the symlink and leave the record behind.
|
|
477
|
-
real_plan_path() { # $1 = plan file as found
|
|
478
|
-
local p="$1" d b t
|
|
479
|
-
d=$(cd "$(dirname "$p")" 2>/dev/null && pwd) || return 1
|
|
480
|
-
b=$(basename "$p")
|
|
481
|
-
t=$(readlink "$d/$b" 2>/dev/null || true)
|
|
482
|
-
if [ -n "$t" ]; then
|
|
483
|
-
case "$t" in
|
|
484
|
-
/*) d=$(cd "$(dirname "$t")" 2>/dev/null && pwd) || return 1 ;;
|
|
485
|
-
*) d=$(cd "$d/$(dirname "$t")" 2>/dev/null && pwd) || return 1 ;;
|
|
486
|
-
esac
|
|
487
|
-
b=$(basename "$t")
|
|
488
|
-
fi
|
|
489
|
-
case "$d" in
|
|
490
|
-
"$repo_root") printf '%s' "$b" ;;
|
|
491
|
-
"$repo_root"/*) printf '%s/%s' "${d#$repo_root/}" "$b" ;;
|
|
492
|
-
*) return 1 ;;
|
|
493
|
-
esac
|
|
6
|
+
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
7
|
+
bundle="$script_dir/board/plot-approve.mjs"
|
|
8
|
+
[ -f "$bundle" ] || {
|
|
9
|
+
echo "plot-approve: cannot find $bundle — update the plot plugin in this repository, or — in the plot repository itself — run: pnpm build:board" >&2
|
|
10
|
+
exit 2
|
|
494
11
|
}
|
|
495
|
-
|
|
496
|
-
rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
|
|
497
|
-
[ -n "$rel" ] || die "$plan_file is outside the repository root ($repo_root).
|
|
498
|
-
Move the plan under $PLAN_DIR inside this checkout and re-run."
|
|
499
|
-
|
|
500
|
-
# Flip `**State:** Draft` OR `**State:** Design` → `Approved` in the `## Status`
|
|
501
|
-
# section only. Both are the pre-Approved states this script advances from.
|
|
502
|
-
#
|
|
503
|
-
# Reads `State:` and `Phase:` alike: it changes the VALUE on whichever line
|
|
504
|
-
# carries it, so a plan written before the 2026-09-07 rename still approves.
|
|
505
|
-
#
|
|
506
|
-
# Scoped to that section because a plan that QUOTES a status block in its prose
|
|
507
|
-
# (this repo has several, documenting the format) would otherwise have its
|
|
508
|
-
# illustration rewritten too — a silent corruption of the very files that
|
|
509
|
-
# specify the format.
|
|
510
|
-
#
|
|
511
|
-
# READS ONE FILE AND WRITES ANOTHER, rather than editing in place. It edited in
|
|
512
|
-
# place until 2026-09-02, which is what let the phase land without its record —
|
|
513
|
-
# see write_transition() below.
|
|
514
|
-
flip_phase() { # $1=in $2=out → 0 if it changed the file, 1 if there was nothing to flip
|
|
515
|
-
awk '
|
|
516
|
-
BEGIN { section = ""; done = 0 }
|
|
517
|
-
/^## / { section = ($0 ~ /^## Status/) ? "status" : ""; print; next }
|
|
518
|
-
section == "status" && !done && tolower($0) ~ /^[ \t]*[-*]?[ \t]*\**(state|phase)[:*]/ {
|
|
519
|
-
if (tolower($0) ~ /draft/) {
|
|
520
|
-
sub(/[Dd]raft/, "Approved")
|
|
521
|
-
done = 1
|
|
522
|
-
changed = 1
|
|
523
|
-
} else if (tolower($0) ~ /design/) {
|
|
524
|
-
sub(/[Dd]esign/, "Approved")
|
|
525
|
-
done = 1
|
|
526
|
-
changed = 1
|
|
527
|
-
}
|
|
528
|
-
}
|
|
529
|
-
{ print }
|
|
530
|
-
END { exit (changed ? 0 : 1) }
|
|
531
|
-
' "$1" > "$2"
|
|
532
|
-
}
|
|
533
|
-
|
|
534
|
-
# Insert one `- **Approved:** ...` line into the plan's `## Status` section.
|
|
535
|
-
#
|
|
536
|
-
# THIS IS append_started_line()'s SHAPE, DELIBERATELY. That function
|
|
537
|
-
# (plot-dispatch.sh:423) was repaired on 2026-08-17 after appending below
|
|
538
|
-
# `- **Delivered:**` instead of filling the empty placeholder the template
|
|
539
|
-
# ships — the parser still read it, so nothing failed loudly, but the block
|
|
540
|
-
# listed a start after a delivery and two plans had to be tidied by hand.
|
|
541
|
-
# A second implementation that re-derived the awk would repeat exactly that
|
|
542
|
-
# bug, so this one fills the placeholder first and only falls back to appending
|
|
543
|
-
# after the last list item for plans that never had one (pre-Plot-2 files).
|
|
544
|
-
#
|
|
545
|
-
# A plan with no `## Status` heading is a REFUSAL, not a best-effort append:
|
|
546
|
-
# plot-plan-meta.sh reads these records out of that section, so a line below it
|
|
547
|
-
# parses as nothing at all — a record that exists on disk and not in the data is
|
|
548
|
-
# worse than no record, because it looks written.
|
|
549
|
-
#
|
|
550
|
-
# READS ONE FILE AND WRITES ANOTHER, for the reason flip_phase() gives.
|
|
551
|
-
append_approved_line() { # $1=in $2=out $3=record
|
|
552
|
-
local line
|
|
553
|
-
line="- **Approved:** $3"
|
|
554
|
-
awk -v line="$line" '
|
|
555
|
-
{ lines[++n] = $0 }
|
|
556
|
-
END {
|
|
557
|
-
for (i = 1; i <= n; i++) {
|
|
558
|
-
if (lines[i] ~ /^##[ \t]*[Ss]tatus[ \t]*$/) { start = i; break }
|
|
559
|
-
}
|
|
560
|
-
if (!start) exit 1
|
|
561
|
-
|
|
562
|
-
insert = start
|
|
563
|
-
for (i = start + 1; i <= n; i++) {
|
|
564
|
-
if (lines[i] ~ /^##[ \t]/) break
|
|
565
|
-
# An HTML comment ends the writable region. Checked BEFORE the
|
|
566
|
-
# placeholder arms so a commented-out `- **Approved:**` template line
|
|
567
|
-
# is never mistaken for the slot to fill.
|
|
568
|
-
if (lines[i] ~ /<!--/) break
|
|
569
|
-
if (lines[i] ~ /^[ \t]*[-*][ \t]*\*\*Approved:\*\*[ \t]*$/) { slot = i; break }
|
|
570
|
-
if (lines[i] ~ /^[ \t]*[-*][ \t]/) insert = i
|
|
571
|
-
}
|
|
572
|
-
|
|
573
|
-
for (i = 1; i <= n; i++) {
|
|
574
|
-
if (i == slot) { print line; continue } # replaces the empty placeholder
|
|
575
|
-
print lines[i]
|
|
576
|
-
if (!slot && i == insert) print line
|
|
577
|
-
}
|
|
578
|
-
}
|
|
579
|
-
' "$1" > "$2"
|
|
580
|
-
}
|
|
581
|
-
|
|
582
|
-
# ---------------------------------------------------------------------------
|
|
583
|
-
# THE TRANSITION — one value, decided in the domain, written whole or not at all
|
|
584
|
-
# ---------------------------------------------------------------------------
|
|
585
|
-
#
|
|
586
|
-
# WHAT THIS CLOSES. The phase and the record were steps 3 and 4 until
|
|
587
|
-
# 2026-09-02, and they were independent: `flip_phase` edited the file, and
|
|
588
|
-
# `append_approved_line` then edited it again. The second could fail — a plan
|
|
589
|
-
# with no `## Status` heading is its documented refusal — and the first had
|
|
590
|
-
# already landed. Measured on the delivery side 2026-08-20, where the same shape
|
|
591
|
-
# had the same bug: a plan carrying `Phase: Delivered` with no `Delivered:` line
|
|
592
|
-
# was filtered out of `plot-fleet-scan.sh` ENTIRELY, which reads its delivered
|
|
593
|
-
# window from the record itself. A phase without its record does not make a plan
|
|
594
|
-
# half-transitioned; it makes it invisible.
|
|
595
|
-
#
|
|
596
|
-
# SO THE TWO ARE ONE WRITE. The domain says so in a type: `transitions/plan.ts`
|
|
597
|
-
# gives `Decision` a required `phase` AND a required `record`, so a decision
|
|
598
|
-
# missing either does not compile. `plot-transition.mjs` carries that value out
|
|
599
|
-
# to here, and this pair of functions is the half that could still have broken
|
|
600
|
-
# it — both edits run against scratch copies, and the plan file is replaced only
|
|
601
|
-
# once both have succeeded.
|
|
602
|
-
#
|
|
603
|
-
# THE DOMAIN DECIDES, THIS PERFORMS. The phase word and the record's text come
|
|
604
|
-
# back from the bundle; the awk that knows where a `## Status` line lives stays
|
|
605
|
-
# here, because that is adaptation and it carries bug history worth keeping
|
|
606
|
-
# (append_started_line()'s placeholder repair, 2026-08-17).
|
|
607
|
-
#
|
|
608
|
-
# IDEMPOTENCE IS UNCHANGED, and it is still the source that answers. The domain
|
|
609
|
-
# reads the phase and the record THIS SCRIPT PARSED FROM THE FILE IT IS ABOUT TO
|
|
610
|
-
# WRITE, and answers `already` when both are present — the same question steps 3
|
|
611
|
-
# and 4 asked separately, asked once. No progress file appears here, because a
|
|
612
|
-
# progress file is exactly what would disagree with the repository when somebody
|
|
613
|
-
# intervened by hand between two runs.
|
|
614
|
-
#
|
|
615
|
-
# THE MERGE IS NOT PART OF IT, and it must not become one. Step 2 merges the PR,
|
|
616
|
-
# and a merged PR cannot be rolled back if a file write then fails. Atomicity
|
|
617
|
-
# stops at the host boundary; re-running is the repair, which is why every step
|
|
618
|
-
# still tests the source it would have written.
|
|
619
|
-
transition_mjs="$script_dir/board/plot-transition.mjs"
|
|
620
|
-
|
|
621
|
-
# Ask the domain for the transition, and refuse in its words.
|
|
622
|
-
#
|
|
623
|
-
# Called with the file's OWN parse rather than the caller's: on the `pr` flow
|
|
624
|
-
# those are different files, and the plan on the default branch is the one that
|
|
625
|
-
# counts.
|
|
626
|
-
decide_transition() { # $1=file $2=channel → prints "<Phase>\t<record>\t<write|already>\t<yes|no>"
|
|
627
|
-
local f="$1" channel="$2" m answer rc
|
|
628
|
-
[ -f "$transition_mjs" ] \
|
|
629
|
-
|| { echo "plot-approve: cannot find $transition_mjs — run 'pnpm build:board'." >&2; return 1; }
|
|
630
|
-
m=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null) || m=""
|
|
631
|
-
[ -n "$m" ] || { echo "plot-approve: cannot parse $f — refusing rather than guessing." >&2; return 1; }
|
|
632
|
-
# THE SLICES TRAVEL WITH THE TRANSITION, not only with the early check above.
|
|
633
|
-
# Measured 2026-10-02 by disabling that check: this call approved an unnamed
|
|
634
|
-
# plan outright — merged, flipped and recorded — because the field line
|
|
635
|
-
# carries no slices and the domain reads an absent reading as unmeasured. So
|
|
636
|
-
# the rule is asked twice, the second time from the file this re-parses, which
|
|
637
|
-
# on the `pr` flow is the plan on the default branch.
|
|
638
|
-
#
|
|
639
|
-
# Out of band rather than a field of its own, which is why `People` widening
|
|
640
|
-
# the line to twelve did not touch this: the slices are a nested list, and
|
|
641
|
-
# `requestFrom` pads nothing.
|
|
642
|
-
local slices_file=""
|
|
643
|
-
plot_tmpfile slices_file approve-transition-slices
|
|
644
|
-
printf '%s' "$m" > "$slices_file"
|
|
645
|
-
answer=$(printf 'approve\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t\t%s\n' \
|
|
646
|
-
"$slug" \
|
|
647
|
-
"$(printf '%s' "$m" | jq -r '.phase // ""')" \
|
|
648
|
-
"$(printf '%s' "$m" | jq -r '.review // ""')" \
|
|
649
|
-
"$(printf '%s' "$m" | jq -r '.approved_raw // ""')" \
|
|
650
|
-
"$(printf '%s' "$m" | jq -r '.delivered_raw // ""')" \
|
|
651
|
-
"$(printf '%s' "$m" | jq -r '.released_raw // ""')" \
|
|
652
|
-
"$today" "$who" "$channel" "$people_csv" \
|
|
653
|
-
| node "$transition_mjs" --slices "$slices_file" 2>&1)
|
|
654
|
-
rc=$?
|
|
655
|
-
rm -f "$slices_file"
|
|
656
|
-
# Exit 1 is the domain's refusal and its sentence, tab-separated after the
|
|
657
|
-
# rule that fired. Exit 2 is this script handing it something unreadable,
|
|
658
|
-
# which no operator can act on — so it reports as the bug it is.
|
|
659
|
-
if [ "$rc" != 0 ]; then
|
|
660
|
-
if [ "$rc" = 1 ]; then
|
|
661
|
-
echo "plot-approve: $(printf '%s' "$answer" | cut -f2-)" >&2
|
|
662
|
-
else
|
|
663
|
-
echo "plot-approve: $answer" >&2
|
|
664
|
-
fi
|
|
665
|
-
return 1
|
|
666
|
-
fi
|
|
667
|
-
printf '%s' "$answer"
|
|
668
|
-
}
|
|
669
|
-
|
|
670
|
-
# Apply the decided transition: the phase and the record, or neither.
|
|
671
|
-
#
|
|
672
|
-
# BOTH EDITS RUN AGAINST SCRATCH FILES and the plan is replaced by one `mv`.
|
|
673
|
-
# An `## Status` section that cannot take the record leaves the file exactly as
|
|
674
|
-
# it was found — INCLUDING ITS PHASE — so re-running is still the repair, and
|
|
675
|
-
# the half-state that made a plan invisible cannot be reached from here.
|
|
676
|
-
#
|
|
677
|
-
# `$3` says whether the file already carries the record. A plan can carry one
|
|
678
|
-
# while its phase lags — written by hand, or an earlier run cut between the two
|
|
679
|
-
# writes — and appending a second would leave the block listing one approval
|
|
680
|
-
# twice. The domain returns the written record unchanged in that case, so the
|
|
681
|
-
# phase still flips and nothing is inserted.
|
|
682
|
-
write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_report record_report
|
|
683
|
-
local f="$1" record="$2" recorded="$3" a="$1.plot-phase" b="$1.plot-record" flipped=0
|
|
684
|
-
|
|
685
|
-
if flip_phase "$f" "$a"; then flipped=1; else flipped=0; fi
|
|
686
|
-
# awk wrote `$a` either way; where nothing flipped it is a faithful copy, so
|
|
687
|
-
# the record still has a file to be inserted into.
|
|
688
|
-
[ -s "$a" ] || { rm -f "$a"; echo "plot-approve: could not read $rel" >&2; return 1; }
|
|
689
|
-
|
|
690
|
-
if [ "$recorded" = "yes" ]; then
|
|
691
|
-
mv "$a" "$f" || { rm -f "$a"; return 1; }
|
|
692
|
-
record_report="already"
|
|
693
|
-
else
|
|
694
|
-
if ! append_approved_line "$a" "$b" "$record"; then
|
|
695
|
-
rm -f "$a" "$b"
|
|
696
|
-
echo "plot-approve: $rel has no '## Status' section — nowhere to record the approval." >&2
|
|
697
|
-
echo " Nothing was written: the phase is not flipped either, because a phase" >&2
|
|
698
|
-
echo " with no record is invisible to the scan. Fix the section and re-run." >&2
|
|
699
|
-
return 1
|
|
700
|
-
fi
|
|
701
|
-
mv "$b" "$f" || { rm -f "$a" "$b"; return 1; }
|
|
702
|
-
rm -f "$a"
|
|
703
|
-
record_report="written"
|
|
704
|
-
fi
|
|
705
|
-
|
|
706
|
-
phase_report=$([ "$flipped" = 1 ] && echo flipped || echo already)
|
|
707
|
-
# The receipt plot-state-gate.sh clears on. Recorded after the `mv`, so it
|
|
708
|
-
# names a value the file actually carries — a receipt written before a failed
|
|
709
|
-
# write would license a commit of the state that was refused.
|
|
710
|
-
record_state_receipt "$f" "Approved"
|
|
711
|
-
return 0
|
|
712
|
-
}
|
|
713
|
-
|
|
714
|
-
# Remove the `.plot/hold` entry for EVERY branch the plan names, and nothing
|
|
715
|
-
# else. String equality on the first field, exactly as the gate reads it
|
|
716
|
-
# (plot-phase-gate.sh:121) — a pattern here would release gates the plan never
|
|
717
|
-
# named. Returns the number of entries removed on stdout.
|
|
718
|
-
clear_holds() { # $1=worktree root; reads $plan_branches
|
|
719
|
-
local root="$1" hold="$1/.plot/hold" removed=0
|
|
720
|
-
[ -f "$hold" ] || { printf '0'; return 0; }
|
|
721
|
-
[ -n "$plan_branches" ] || { printf '0'; return 0; }
|
|
722
|
-
# SPACE-separated, not newline-separated: BSD awk (macOS bash 3.2's awk)
|
|
723
|
-
# rejects a literal newline inside a -v value outright — "newline in string".
|
|
724
|
-
# A git branch name cannot contain a space (git check-ref-format forbids it),
|
|
725
|
-
# so a space is a safe separator where a newline is not portable.
|
|
726
|
-
local list
|
|
727
|
-
list=$(printf '%s' "$plan_branches" | tr '\n' ' ')
|
|
728
|
-
removed=$(awk -v branches="$list" '
|
|
729
|
-
BEGIN { n = split(branches, b, " "); for (i = 1; i <= n; i++) if (b[i] != "") want[b[i]] = 1 }
|
|
730
|
-
($1 in want) { c++; next }
|
|
731
|
-
{ print > OUT }
|
|
732
|
-
END { print c + 0 }
|
|
733
|
-
' OUT="$hold.plot-tmp" "$hold")
|
|
734
|
-
# awk never creates OUT when every line matched; an empty hold file is the
|
|
735
|
-
# honest result of removing the last entry, not a reason to leave it.
|
|
736
|
-
[ -f "$hold.plot-tmp" ] || : > "$hold.plot-tmp"
|
|
737
|
-
mv "$hold.plot-tmp" "$hold"
|
|
738
|
-
printf '%s' "$removed"
|
|
739
|
-
}
|
|
740
|
-
|
|
741
|
-
# Update the sprint item annotation this plan appears in:
|
|
742
|
-
# - [ ] [slug] description <!-- pr: #N, branch: feature/slug -->
|
|
743
|
-
# /plot-sprint READS these (`pr`, `branch`) and /plot-approve writes them, so an
|
|
744
|
-
# approval that skips this makes `/plot-sprint status` wrong rather than merely
|
|
745
|
-
# incomplete.
|
|
746
|
-
#
|
|
747
|
-
# `status:` IS GONE, since 2026-09-08. `a-withdrawn-item-is-not-open` measured
|
|
748
|
-
# it dead in both directions — 67 lines carried one, no reader acted on the
|
|
749
|
-
# value, and `plot-sprint-release.sh` read the field nowhere. The plan file
|
|
750
|
-
# carries `State:` and a dated `Approved:` record; a cache nobody refreshes and
|
|
751
|
-
# nobody reads is a second answer waiting to contradict the first. `pr` and
|
|
752
|
-
# `branch` stay: they name things no plan field holds.
|
|
753
|
-
#
|
|
754
|
-
# A plan in NO sprint is a no-op, never an error — that is the common case.
|
|
755
|
-
# Already-done test: the annotation already carries this PR and branch.
|
|
756
|
-
update_sprint_annotation() { # $1=worktree root → prints none|updated|already|missing
|
|
757
|
-
local root="$1" f found=""
|
|
758
|
-
[ -n "$sprint" ] || { printf 'none'; return 0; }
|
|
759
|
-
local dir="$root/${SPRINT_DIR#/}"
|
|
760
|
-
[ -d "$dir" ] || { printf 'missing'; return 0; }
|
|
761
|
-
# Found by CONTENT, not by filename. The `Sprint:` field holds a slug while
|
|
762
|
-
# the file is named `<week>-<slug>.md` — and the week prefix is written in
|
|
763
|
-
# whatever case /plot-sprint's ISO week produced (`2026-W33-...` measured),
|
|
764
|
-
# so a glob on the slug misses it on a case-sensitive filesystem. The item
|
|
765
|
-
# line `- [ ] [<slug>] ...` is the actual relationship, and it is what
|
|
766
|
-
# /plot-sprint reads back.
|
|
767
|
-
for f in "$dir"/*.md; do
|
|
768
|
-
[ -e "$f" ] || continue
|
|
769
|
-
grep -q "\[$slug\]" "$f" 2>/dev/null && { found="$f"; break; }
|
|
770
|
-
done
|
|
771
|
-
[ -n "$found" ] || { printf 'missing'; return 0; }
|
|
772
|
-
|
|
773
|
-
local before after
|
|
774
|
-
before=$(cat "$found")
|
|
775
|
-
after=$(awk -v slug="$slug" -v pr="$pr_number" -v br="$(printf '%s' "$plan_branches" | head -1)" '
|
|
776
|
-
index($0, "[" slug "]") == 0 { print; next }
|
|
777
|
-
{
|
|
778
|
-
line = $0
|
|
779
|
-
if (index(line, "<!--") == 0) {
|
|
780
|
-
print line " <!-- pr: #" pr (br != "" ? ", branch: " br : "") " -->"
|
|
781
|
-
next
|
|
782
|
-
}
|
|
783
|
-
# THE CLOSING MARKER IS SPLIT OFF BEFORE ANY FIELD IS TOUCHED.
|
|
784
|
-
# A value pattern that has to avoid `-->` cannot be written safely:
|
|
785
|
-
# `[^,>]*[^,> \t]` excluded the `>` and still swallowed the `--`, turning
|
|
786
|
-
# ` -->` into a bare `>` and corrupting the comment — measured 2026-09-08,
|
|
787
|
-
# `approve: updates the sprint annotation the sprint view reads` failed on
|
|
788
|
-
# exactly that. Excluding `-` as well is worse: it rewrites `bug/a-b` as
|
|
789
|
-
# `feature/new-b`, and hyphens are in most branch names here.
|
|
790
|
-
# With the marker held aside, every field ends at a comma or at
|
|
791
|
-
# end-of-string, and none can reach it.
|
|
792
|
-
tail = ""
|
|
793
|
-
if (match(line, /[ \t]*-->[ \t]*$/)) { tail = substr(line, RSTART); line = substr(line, 1, RSTART - 1) }
|
|
794
|
-
if (line ~ /pr:[ \t]*#?[0-9a-z]+/) sub(/pr:[ \t]*#?[0-9a-z]+/, "pr: #" pr, line)
|
|
795
|
-
else sub(/<!--/, "<!-- pr: #" pr ",", line)
|
|
796
|
-
if (br != "") {
|
|
797
|
-
if (line ~ /branch:[ \t]*[^,]/) sub(/branch:[ \t]*[^,]*/, "branch: " br, line)
|
|
798
|
-
else line = line ", branch: " br
|
|
799
|
-
}
|
|
800
|
-
print line (tail != "" ? tail : " -->")
|
|
801
|
-
}
|
|
802
|
-
' "$found")
|
|
803
|
-
if [ "$before" = "$after" ]; then printf 'already'; return 0; fi
|
|
804
|
-
printf '%s\n' "$after" > "$found"
|
|
805
|
-
printf 'updated'
|
|
806
|
-
}
|
|
807
|
-
|
|
808
|
-
# The whole local half, run inside one directory — the booking worktree in the
|
|
809
|
-
# `pr` flow, the caller's own repo root in the `same branch` / direct flow.
|
|
810
|
-
apply_local_writes() { # $1=root → sets phase_report record_report holds_report sprint_report
|
|
811
|
-
local root="$1" f="$1/$rel"
|
|
812
|
-
[ -f "$f" ] || { echo "plot-approve: $rel is not present in $root" >&2; return 1; }
|
|
813
|
-
|
|
814
|
-
# Step 3 — THE TRANSITION: the phase and its record, together or not at all.
|
|
815
|
-
#
|
|
816
|
-
# ONE STEP WHERE THERE WERE TWO, which is the whole of this change. The domain
|
|
817
|
-
# decides what the two lines say and whether they are owed at all; this writes
|
|
818
|
-
# them as one replacement of the file. Already-done test: the domain answers
|
|
819
|
-
# `already` when the file it is about to write ALREADY carries both — re-parsed
|
|
820
|
-
# here rather than trusted from the caller's copy, because on the `pr` flow
|
|
821
|
-
# those are different files and the plan on the default branch is the one that
|
|
822
|
-
# counts.
|
|
823
|
-
local write_channel="plan-PR #$pr_number merged"
|
|
824
|
-
[ "$same_branch" = 1 ] && write_channel="plan-PR #$pr_number reviewed"
|
|
825
|
-
[ "$in_session" = 1 ] && write_channel="$channel"
|
|
826
|
-
local decided record action recorded
|
|
827
|
-
decided=$(decide_transition "$f" "$write_channel") || return 1
|
|
828
|
-
record=$(printf '%s' "$decided" | cut -f2)
|
|
829
|
-
action=$(printf '%s' "$decided" | cut -f3)
|
|
830
|
-
recorded=$(printf '%s' "$decided" | cut -f4)
|
|
831
|
-
if [ "$action" = "already" ]; then
|
|
832
|
-
phase_report="already"
|
|
833
|
-
record_report="already"
|
|
834
|
-
else
|
|
835
|
-
write_transition "$f" "$record" "$recorded" || return 1
|
|
836
|
-
fi
|
|
837
|
-
|
|
838
|
-
# Step 5 — clear the holds, keyed by branch.
|
|
839
|
-
holds_report=$(clear_holds "$root")
|
|
840
|
-
|
|
841
|
-
# Step 6 — the sprint annotation.
|
|
842
|
-
sprint_report=$(update_sprint_annotation "$root")
|
|
843
|
-
return 0
|
|
844
|
-
}
|
|
845
|
-
|
|
846
|
-
phase_report="" record_report="" holds_report="0" sprint_report="none"
|
|
847
|
-
push_report="n/a"
|
|
848
|
-
|
|
849
|
-
# `Impl: same branch` records on the work branch, in place. Everything else
|
|
850
|
-
# records on the default branch, through a disposable branch.
|
|
851
|
-
if [ "$same_branch" = 1 ]; then
|
|
852
|
-
apply_local_writes "$repo_root" || exit 1
|
|
853
|
-
git -C "$repo_root" add -- "$rel" >/dev/null 2>&1 || true
|
|
854
|
-
[ -f "$repo_root/.plot/hold" ] && git -C "$repo_root" add -- .plot/hold >/dev/null 2>&1
|
|
855
|
-
[ "$sprint_report" = "updated" ] && git -C "$repo_root" add -- "${SPRINT_DIR#/}" >/dev/null 2>&1
|
|
856
|
-
if git -C "$repo_root" diff --cached --quiet 2>/dev/null; then
|
|
857
|
-
push_report="nothing-to-commit"
|
|
858
|
-
echo "step: nothing to commit — the approval was already recorded"
|
|
859
|
-
else
|
|
860
|
-
git -C "$repo_root" commit -q -m "plot: approve $slug" || die "could not commit the approval.
|
|
861
|
-
The PR is already merged; the local record is what is missing. See what git
|
|
862
|
-
refused: git -C $repo_root status. Then re-run this — it is idempotent."
|
|
863
|
-
push_report="local"
|
|
864
|
-
echo "step: recorded on $(git -C "$repo_root" branch --show-current) — push it with the implementation"
|
|
865
|
-
fi
|
|
866
|
-
else
|
|
867
|
-
# Fetched even under --offline: recording is a push, so the network is
|
|
868
|
-
# already required, and a stale origin/<default> guarantees a
|
|
869
|
-
# non-fast-forward. --offline is honoured everywhere it can be, and this is
|
|
870
|
-
# not one of those places.
|
|
871
|
-
git fetch -q origin "$MAIN" 2>/dev/null
|
|
872
|
-
|
|
873
|
-
bookbr="plot/approve-$slug"
|
|
874
|
-
tmpwt="$wt_root/.plot-approve-$slug.$$"
|
|
875
|
-
# `git worktree add` creates the desk root when it is missing, so exclude it
|
|
876
|
-
# first: a booking run must not leave `.worktrees/` untracked in `git status`.
|
|
877
|
-
plot_exclude_desk_root "$main_root"
|
|
878
|
-
# -B: a leftover branch from an earlier failed run must not block this one.
|
|
879
|
-
# It is disposable by construction — created here, pushed, deleted.
|
|
880
|
-
git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \
|
|
881
|
-
|| die "could not prepare a booking worktree at $tmpwt.
|
|
882
|
-
Most often origin/$MAIN is not fetched, or '$bookbr' is checked out in
|
|
883
|
-
another worktree. Check both: git fetch origin $MAIN && git worktree list
|
|
884
|
-
Nothing has been written locally; the plan is untouched."
|
|
885
|
-
|
|
886
|
-
cleanup() {
|
|
887
|
-
git worktree remove --force "$tmpwt" >/dev/null 2>&1 || true
|
|
888
|
-
git branch -D "$bookbr" >/dev/null 2>&1 || true
|
|
889
|
-
}
|
|
890
|
-
|
|
891
|
-
if ! apply_local_writes "$tmpwt"; then
|
|
892
|
-
cleanup
|
|
893
|
-
exit 1
|
|
894
|
-
fi
|
|
895
|
-
|
|
896
|
-
git -C "$tmpwt" add -- "$rel" >/dev/null 2>&1 || true
|
|
897
|
-
[ -f "$tmpwt/.plot/hold" ] && git -C "$tmpwt" add -- .plot/hold >/dev/null 2>&1
|
|
898
|
-
[ "$sprint_report" = "updated" ] && git -C "$tmpwt" add -- "${SPRINT_DIR#/}" >/dev/null 2>&1
|
|
899
|
-
|
|
900
|
-
if git -C "$tmpwt" diff --cached --quiet 2>/dev/null; then
|
|
901
|
-
# THE IDEMPOTENT EXIT. Everything this run would have written was already
|
|
902
|
-
# on the default branch, so there is nothing to push and nothing wrong.
|
|
903
|
-
push_report="nothing-to-commit"
|
|
904
|
-
echo "step: nothing to commit — the approval is already recorded on $MAIN"
|
|
905
|
-
cleanup
|
|
906
|
-
else
|
|
907
|
-
if ! git -C "$tmpwt" -c "user.name=$who" commit -q -m "plot: approve $slug"; then
|
|
908
|
-
cleanup
|
|
909
|
-
die "could not commit the approval"
|
|
910
|
-
fi
|
|
911
|
-
# plot-push-main.sh rather than a bare `git push`: a repo whose protection
|
|
912
|
-
# is configured but NOT ENFORCED waves the push through with exit 0 and
|
|
913
|
-
# only a notice on stderr, so a bare push cannot tell a bypass from a clean
|
|
914
|
-
# landing. Its words are carried verbatim — which rules were stepped over
|
|
915
|
-
# and which checks did not run is information only the remote has.
|
|
916
|
-
push_out=$(bash "$script_dir/plot-push-main.sh" "$bookbr" "$MAIN" 2>&1)
|
|
917
|
-
push_rc=$?
|
|
918
|
-
printf '%s\n' "$push_out" | sed 's/^/ /'
|
|
919
|
-
if [ "$push_rc" = 0 ]; then
|
|
920
|
-
push_report=$(printf '%s' "$push_out" | sed -n 's/^push: \([a-z]*\).*/\1/p' | head -1)
|
|
921
|
-
[ -n "$push_report" ] || push_report="unknown"
|
|
922
|
-
cleanup
|
|
923
|
-
else
|
|
924
|
-
# BRANCH PROTECTION FALLBACK — the only path where a micro-PR is right.
|
|
925
|
-
# Never leave the approved plan stranded at `Phase: Draft`: the approval
|
|
926
|
-
# is decided and irreversible once committed, so the recorded phase must
|
|
927
|
-
# follow it.
|
|
928
|
-
micro_body="Records the approval of \`$slug\` (plan-PR #$pr_number merged)."
|
|
929
|
-
[ "$in_session" = 1 ] && micro_body="Records the in-session approval of \`$slug\` by $who."
|
|
930
|
-
echo "step: push rejected — opening a micro-PR instead"
|
|
931
|
-
if git push -q origin "$bookbr" 2>/dev/null \
|
|
932
|
-
&& micro_url=$(bash "$script_dir/plot-host.sh" pr-create \
|
|
933
|
-
--title "plot: approve $slug" \
|
|
934
|
-
--body "$micro_body" \
|
|
935
|
-
--base "$MAIN" --head "$bookbr" 2>/dev/null) \
|
|
936
|
-
&& micro_num=$(printf '%s' "$micro_url" | sed 's#.*/##') \
|
|
937
|
-
&& bash "$script_dir/plot-host.sh" pr-merge "$micro_num" --delete-branch >/dev/null 2>&1
|
|
938
|
-
then
|
|
939
|
-
push_report="micro-pr"
|
|
940
|
-
echo "step: approval landed via micro-PR $micro_url"
|
|
941
|
-
cleanup
|
|
942
|
-
else
|
|
943
|
-
push_report="rejected"
|
|
944
|
-
stranded_reason="PR #$pr_number IS MERGED"
|
|
945
|
-
[ "$in_session" = 1 ] && stranded_reason="the in-session approval IS DECIDED"
|
|
946
|
-
echo "plot-approve: the approval is committed on '$bookbr' but could not reach $MAIN." >&2
|
|
947
|
-
echo " $stranded_reason — the plan must not stay at Phase: Draft." >&2
|
|
948
|
-
echo " Land '$bookbr' by hand, or re-run this command once the push works." >&2
|
|
949
|
-
git worktree remove --force "$tmpwt" >/dev/null 2>&1 || true
|
|
950
|
-
echo "summary: merged=$merged_report phase=$phase_report record=$record_report holds=$holds_report sprint=$sprint_report push=$push_report"
|
|
951
|
-
exit 1
|
|
952
|
-
fi
|
|
953
|
-
fi
|
|
954
|
-
fi
|
|
955
|
-
fi
|
|
956
|
-
|
|
957
|
-
# THE LOG REPLACES A COUNT, NEVER A RECEIPT. Appended ONLY after the push
|
|
958
|
-
# landed this run — `nothing-to-commit` means an earlier run already recorded
|
|
959
|
-
# this approval (and, with it, this row), so appending again would double a
|
|
960
|
-
# count that exists to say how many in-session approvals happened, not how
|
|
961
|
-
# many times this script ran. A refused or interrupted run reaches neither
|
|
962
|
-
# this line nor a row, which is `plot-agent-settings.sh`'s rule applied here:
|
|
963
|
-
# read the exit code, not the emptiness.
|
|
964
|
-
if [ "$in_session" = 1 ] && [ "$push_report" != "nothing-to-commit" ] && [ "$push_report" != "n/a" ]; then
|
|
965
|
-
entry="script"
|
|
966
|
-
[ "${PLOT_APPROVE_ENTRY:-}" = "board" ] && entry="board"
|
|
967
|
-
log_dir="$main_root/.plot/state"
|
|
968
|
-
mkdir -p "$log_dir" 2>/dev/null \
|
|
969
|
-
&& printf '%s\t%s\t%s\t%s\n' "$today" "$slug" "$who" "$entry" >> "$log_dir/in-session-approvals.tsv" 2>/dev/null
|
|
970
|
-
fi
|
|
971
|
-
|
|
972
|
-
echo "summary: merged=$merged_report phase=$phase_report record=$record_report holds=$holds_report sprint=$sprint_report push=$push_report"
|
|
973
|
-
# THE RECEIPT IS SPENT HERE, on the action COMPLETING — never at the gate.
|
|
974
|
-
# `plot-controller-gate.sh` clears on a receipt and LEAVES it, so an
|
|
975
|
-
# interrupted run can be repeated on the same licence: this script documents
|
|
976
|
-
# re-running as the repair for any interruption after its irreversible step,
|
|
977
|
-
# and a receipt spent at the gate would refuse that repair in the case it is
|
|
978
|
-
# most needed. One authorisation, one completed action.
|
|
979
|
-
spend_action_receipt "plot-approve.sh"
|
|
980
|
-
|
|
981
|
-
exit 0
|
|
12
|
+
exec node "$bundle" "$@"
|