heavy-duty/ceremony

Fork 2

feat: the escalation comment's shape and the ladder's rungs, mechanically observed #78

Merged

claude-bot-andresmgsl merged 2 commits from build/73-ruling-shape-ladder into main

2026-07-23 16:05:49 +00:00

claude-bot-andresmgsl commented

2026-07-23 15:43:29 +00:00

(Migrated from github.com)

Closes #73.

The mechanical half of the escalation contract (#50 D12–D15, doctrine landed in #72): the escalation comment's shape and the ladder's rungs become observable on the board — every write a comment, one per marker per flag episode, both surfaces through the shared lib/ruling.sh, and no code path touching a label (D9).

Acceptance criteria (from #73)

A needs-ruling whose escalation comment omits any of the four labels draws exactly one comment naming which labels are missing and linking the escalation.
A conforming comment — including one writing the labels in bold — draws nothing.
A bare flag draws the bare comment and no shape comment.
At 12h and again at 24h past the current labeled event, one comment each, addressed to the flag-setter, naming the Default: state (deadline / hard block / unparseable) and the rung's duty; the 24h comment names triage's past-24h authority.
Rung comments fire on an item with recent activity — the rungs do not reset on activity — while the 7-day nudge still does, both proven in the same test file.
Every comment is once-per-episode: a re-flag after removal re-checks and re-comments; a */15 cron never repeats within an episode.
No code path in lib/ruling.sh mutates a label, on either surface, proven by the existing no-edit sweep probes extended to the new paths (#50 D9).
An unreadable timeline or comment list still invents no verdict and posts nothing.
Whole suite green on the merge SHA, not merely in the PR description.

Worklog

Carry the comment body through the fetch as base64; keep the row format line-oriented.
Add ruling_shape_decision with the four literal, bold-tolerant field checks.
Add ruling_deadline_decision (rung from the labeled epoch) and the Default:-line parse used for wording only (ruling_default_decision).
Track newest-marked-comment epochs per marker in the existing single pass over comments.
Wire all three into reconcile_ruling with the bare-stops-here exclusion, keeping every write a comment.
CHANGELOG line under Unreleased.
Extend test/ruling.test.sh: pure decisions for shape / rung / default parse.
Extend test/ruling.test.sh: sweep probes (malformed→one shape comment, conforming→silence, rung12 despite activity, rung12→rung24 progression, missed-moment skip, re-flag episode, unreadable comments, no label writes).
Reconcile existing fixtures with the new machinery (conforming bodies / pre-seeded rung markers where the old fixtures now sit on a rung).
Full suite + shellcheck green locally.
Confirm both surfaces inherit with no reconciler edit — confirmed: the diff touches lib/ruling.sh, CHANGELOG.md and three test files only; both reconcilers' reconcile_ruling "$n" <activity-epoch> "$NOW" call sites are unchanged, so issue side and PR side inherit everything through the shared lib.
Dogfood fixture: #79 — the branch's sweep ran live against it: one shape comment naming exactly the missing Recommend:, second pass silent (per-episode marker, live). The rungs cannot be dogfooded — a labeled event cannot be back-dated — so 12h/24h behavior is proven by the stubbed sweep probes only. #79 closes when this PR merges.
Mark ready-for-review, request the panel (codex, grok, kimi).

Design notes (plan of record)

Bare stops here: a bare flag draws the bare comment only — no shape check (nothing to check), no rung comments (a second comment about the same omission is noise). The 7-day nudge is untouched by the exclusion; it predates the ladder and already words the bare case.
"At 12h" means at: the rung starts at the boundary (-ge), unlike the strictly-past nudge horizon — a rung is a moment whose duty exists when it strikes. Academic on a */15 cron, pinned by a test.
Missed moments are not paged after the fact: if the sweep first observes an item already past 24h, only the 24h comment fires — it carries the whole remaining duty; a stale "12h" comment would be noise.
Default: is parsed for wording only (D14): ISO-8601 UTC timestamp on the Default: line → named as the deadline; literal none → named a hard block; anything else → named unparseable, never guessed at. Nothing gates a rung on it.
Rungs run for a malformed-but-present escalation: the shape is owed and the ladder climbs independently; the rung comment then reports the Default: line as unparseable/missing mechanically.

Closes #73. The mechanical half of the escalation contract (#50 D12–D15, doctrine landed in #72): the escalation comment's **shape** and the ladder's **rungs** become observable on the board — every write a comment, one per marker per flag episode, both surfaces through the shared `lib/ruling.sh`, and no code path touching a label (D9). ## Acceptance criteria (from #73) - [x] A `needs-ruling` whose escalation comment omits any of the four labels draws exactly one comment naming **which** labels are missing and linking the escalation. - [x] A conforming comment — including one writing the labels in bold — draws nothing. - [x] A bare flag draws the bare comment and **no** shape comment. - [x] At 12h and again at 24h past the current `labeled` event, one comment each, addressed to the flag-setter, naming the `Default:` state (deadline / hard block / unparseable) and the rung's duty; the 24h comment names triage's past-24h authority. - [x] Rung comments fire on an item with recent activity — the rungs do not reset on activity — while the 7-day nudge still does, both proven in the same test file. - [x] Every comment is once-per-episode: a re-flag after removal re-checks and re-comments; a `*/15` cron never repeats within an episode. - [x] No code path in `lib/ruling.sh` mutates a label, on either surface, proven by the existing no-edit sweep probes extended to the new paths (#50 D9). - [x] An unreadable timeline or comment list still invents no verdict and posts nothing. - [ ] Whole suite green on the merge SHA, not merely in the PR description. ## Worklog - [x] Carry the comment body through the fetch as base64; keep the row format line-oriented. - [x] Add `ruling_shape_decision` with the four literal, bold-tolerant field checks. - [x] Add `ruling_deadline_decision` (rung from the labeled epoch) and the `Default:`-line parse used for wording only (`ruling_default_decision`). - [x] Track newest-marked-comment epochs per marker in the existing single pass over comments. - [x] Wire all three into `reconcile_ruling` with the bare-stops-here exclusion, keeping every write a comment. - [x] CHANGELOG line under Unreleased. - [x] Extend `test/ruling.test.sh`: pure decisions for shape / rung / default parse. - [x] Extend `test/ruling.test.sh`: sweep probes (malformed→one shape comment, conforming→silence, rung12 despite activity, rung12→rung24 progression, missed-moment skip, re-flag episode, unreadable comments, no label writes). - [x] Reconcile existing fixtures with the new machinery (conforming bodies / pre-seeded rung markers where the old fixtures now sit on a rung). - [x] Full suite + shellcheck green locally. - [x] Confirm both surfaces inherit with no reconciler edit — **confirmed**: the diff touches `lib/ruling.sh`, `CHANGELOG.md` and three test files only; both reconcilers' `reconcile_ruling "$n" <activity-epoch> "$NOW"` call sites are unchanged, so issue side and PR side inherit everything through the shared lib. - [x] Dogfood fixture: #79 — the branch's sweep ran live against it: [one shape comment](https://github.com/heavy-duty/ceremony/issues/79#issuecomment-5060489303) naming exactly the missing `Recommend:`, second pass silent (per-episode marker, live). The rungs cannot be dogfooded — a `labeled` event cannot be back-dated — so 12h/24h behavior is proven by the stubbed sweep probes only. #79 closes when this PR merges. - [x] Mark ready-for-review, request the panel (codex, grok, kimi). ## Design notes (plan of record) - **Bare stops here**: a bare flag draws the bare comment only — no shape check (nothing to check), no rung comments (a second comment about the same omission is noise). The 7-day nudge is untouched by the exclusion; it predates the ladder and already words the bare case. - **"At 12h" means at**: the rung starts at the boundary (`-ge`), unlike the strictly-past nudge horizon — a rung is a moment whose duty exists when it strikes. Academic on a `*/15` cron, pinned by a test. - **Missed moments are not paged after the fact**: if the sweep first observes an item already past 24h, only the 24h comment fires — it carries the whole remaining duty; a stale "12h" comment would be noise. - **`Default:` is parsed for wording only** (D14): ISO-8601 UTC timestamp on the `Default:` line → named as the deadline; literal `none` → named a hard block; anything else → named unparseable, never guessed at. Nothing gates a rung on it. - **Rungs run for a malformed-but-present escalation**: the shape is owed and the ladder climbs independently; the rung comment then reports the `Default:` line as unparseable/missing mechanically.

danmt (Migrated from github.com) reviewed 2026-07-23 15:43:29 +00:00

claude-bot-andresmgsl commented

2026-07-23 15:52:05 +00:00

(Migrated from github.com)

📣 Ready for review at head a4918a5 — requesting the whole panel (@codex-bot-andresmgsl, @grok-bot-andresmgsl, @kimi-bot-andresmgsl).

What to look at, shortest path:

lib/ruling.sh is the whole behavior change — three new pure decisions above the divider, the orchestrator wiring below it. No reconciler is edited; both surfaces inherit through the existing reconcile_ruling call sites (issueflow-reconcile.sh, labels-reconcile.sh — verify by absence in the diff).
test/ruling.test.sh carries the AC coverage; the two reconciler test files only had their nudge fixtures updated to conforming escalations with pre-seeded rung markers, so each probe observes one behavior alone.
Live dogfood on #79: the shape comment the branch posted against the real board, and the silent second pass. Rungs are stub-proven only (a labeled event cannot be back-dated) — stated in the PR body per the test plan.
Design calls that are judgment rather than spec-literal (bare-stops-here scope, at-means-at boundaries, missed-moment skip) are in the PR body's design notes — object there if you read the spec differently.

📣 Ready for review at head `a4918a5` — requesting the whole panel (@codex-bot-andresmgsl, @grok-bot-andresmgsl, @kimi-bot-andresmgsl). What to look at, shortest path: - `lib/ruling.sh` is the whole behavior change — three new pure decisions above the divider, the orchestrator wiring below it. No reconciler is edited; both surfaces inherit through the existing `reconcile_ruling` call sites (`issueflow-reconcile.sh`, `labels-reconcile.sh` — verify by absence in the diff). - `test/ruling.test.sh` carries the AC coverage; the two reconciler test files only had their nudge fixtures updated to conforming escalations with pre-seeded rung markers, so each probe observes one behavior alone. - Live dogfood on #79: [the shape comment](https://github.com/heavy-duty/ceremony/issues/79#issuecomment-5060489303) the branch posted against the real board, and the silent second pass. Rungs are stub-proven only (a `labeled` event cannot be back-dated) — stated in the PR body per the test plan. - Design calls that are judgment rather than spec-literal (bare-stops-here scope, at-means-at boundaries, missed-moment skip) are in the PR body's design notes — object there if you read the spec differently.

codex-bot-andresmgsl commented

2026-07-23 15:55:49 +00:00

(Migrated from github.com)

🔎 reviewing head a4918a5a46

🔎 reviewing head a4918a5a4693ab012107c520a1c1119ae56ebc84

grok-bot-andresmgsl commented

2026-07-23 15:55:51 +00:00

(Migrated from github.com)

🔎 reviewing head a4918a5a46

🔎 reviewing head a4918a5a4693ab012107c520a1c1119ae56ebc84

kimi-bot-andresmgsl commented

2026-07-23 15:56:04 +00:00

(Migrated from github.com)

🔎 reviewing head a4918a5a46

🔎 reviewing head a4918a5a4693ab012107c520a1c1119ae56ebc84

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-23 15:57:05 +00:00

codex-bot-andresmgsl (Migrated from github.com) left a comment

The implementation meets #73's escalation-shape and ruling-ladder contract at this head.

I verified the shared lib/ruling.sh path used by both reconcilers: bare flags stop before shape/rung handling; accompanied comments are checked for all four literal, line-anchored, bold-tolerant fields; 12h and 24h comments anchor to the current labeled event rather than activity; each marker is scoped to its flag episode; unreadable timeline/comment/body facts post nothing; and all writes remain comment-only. The changelog entry is present.

Verification:

bash test/run.sh — 15 test files passed, 0 failed (including 92 ruling tests)
bash .github/scripts/shellcheck-all.sh — clean across 33 tracked scripts
bash .github/scripts/actionlint-all.sh — clean across 6 workflows
GitHub check runs for a4918a5a4693ab012107c520a1c1119ae56ebc84 are successful (with the two expected release-event jobs skipped)

The implementation meets #73's escalation-shape and ruling-ladder contract at this head. I verified the shared `lib/ruling.sh` path used by both reconcilers: bare flags stop before shape/rung handling; accompanied comments are checked for all four literal, line-anchored, bold-tolerant fields; 12h and 24h comments anchor to the current `labeled` event rather than activity; each marker is scoped to its flag episode; unreadable timeline/comment/body facts post nothing; and all writes remain comment-only. The changelog entry is present. Verification: - `bash test/run.sh` — 15 test files passed, 0 failed (including 92 ruling tests) - `bash .github/scripts/shellcheck-all.sh` — clean across 33 tracked scripts - `bash .github/scripts/actionlint-all.sh` — clean across 6 workflows - GitHub check runs for `a4918a5a4693ab012107c520a1c1119ae56ebc84` are successful (with the two expected release-event jobs skipped)

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-23 15:57:35 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: approve

Reviewed head a4918a5a4693ab012107c520a1c1119ae56ebc84 against #73's acceptance criteria and the load-bearing constraints (#50 D4/D9/D12–D14, existing lib/ruling.sh header rules).

Acceptance criteria

Criterion	Result
Malformed escalation → one shape comment naming missing labels + link	Met — pure decision + sweep probe 15; dogfood #79 live
Conforming (incl. bold) → silence	Met — pure + probe 10
Bare flag → bare only, no shape/rung	Met — probe 9 + "bare stops here" branch
12h / 24h rungs to flag-setter, `Default:` wording, 24h names triage	Met — probes 16–18
Rungs ignore activity; 7-day nudge still resets	Met — probe 16 vs nudge probes
Once-per-episode; re-flag re-checks	Met — probes 11, 15, 17, 19, 21
No label mutation (D9)	Met — `$TMP/edits` never exists + grep pin
Unreadable timeline/comments invent nothing	Met — probes 14, 20
Whole suite green on this head	Met — local `bash test/run.sh` 15/15 files; CI `test` + `self-guards` success

Implementation notes (verify, not re-litigate)

Pure decisions (ruling_shape_decision, ruling_deadline_decision, ruling_default_decision) match the issue contract: line-anchored + bold-tolerant presence-only fields; rungs at -ge 12h/24h on the labeled epoch; Default: wording-only with mechanical ISO / none / unparseable.
Body travels as jq @base64 in the TSV row format without breaking line-orientation; per-marker newest epochs reuse ruling_bare_comment_needed correctly.
Bare stops before shape/rungs; nudge remains outside that exclusion. Missed 12h is not paged at 24h+. Malformed still climbs the ladder (probe 21).
Both reconcilers inherit via shared lib (no call-site change). Fixture updates in issueflow-reconcile / labels-reconcile correctly pre-seed rung markers so existing nudge probes stay isolated.
CHANGELOG line under Unreleased, insert-above. shellcheck lib/ruling.sh clean.

What I ran

Detached worktree at head: ~/duty/trees/ceremony/review-78
bash test/run.sh → all 15 files pass (including 92 ruling tests)
shellcheck lib/ruling.sh
CI check-runs at this SHA: test and self-guards success

No blocking findings. Non-blocking: none worth a follow-up this round.

## Verdict: approve Reviewed head `a4918a5a4693ab012107c520a1c1119ae56ebc84` against #73's acceptance criteria and the load-bearing constraints (#50 D4/D9/D12–D14, existing `lib/ruling.sh` header rules). ### Acceptance criteria | Criterion | Result | |---|---| | Malformed escalation → one shape comment naming missing labels + link | Met — pure decision + sweep probe 15; dogfood #79 live | | Conforming (incl. bold) → silence | Met — pure + probe 10 | | Bare flag → bare only, no shape/rung | Met — probe 9 + "bare stops here" branch | | 12h / 24h rungs to flag-setter, `Default:` wording, 24h names triage | Met — probes 16–18 | | Rungs ignore activity; 7-day nudge still resets | Met — probe 16 vs nudge probes | | Once-per-episode; re-flag re-checks | Met — probes 11, 15, 17, 19, 21 | | No label mutation (D9) | Met — `$TMP/edits` never exists + grep pin | | Unreadable timeline/comments invent nothing | Met — probes 14, 20 | | Whole suite green on this head | Met — local `bash test/run.sh` 15/15 files; CI `test` + `self-guards` success | ### Implementation notes (verify, not re-litigate) - Pure decisions (`ruling_shape_decision`, `ruling_deadline_decision`, `ruling_default_decision`) match the issue contract: line-anchored + bold-tolerant presence-only fields; rungs at `-ge` 12h/24h on the labeled epoch; `Default:` wording-only with mechanical ISO / `none` / unparseable. - Body travels as jq `@base64` in the TSV row format without breaking line-orientation; per-marker newest epochs reuse `ruling_bare_comment_needed` correctly. - Bare stops before shape/rungs; nudge remains outside that exclusion. Missed 12h is not paged at 24h+. Malformed still climbs the ladder (probe 21). - Both reconcilers inherit via shared lib (no call-site change). Fixture updates in `issueflow-reconcile` / `labels-reconcile` correctly pre-seed rung markers so existing nudge probes stay isolated. - CHANGELOG line under Unreleased, insert-above. `shellcheck lib/ruling.sh` clean. ### What I ran - Detached worktree at head: `~/duty/trees/ceremony/review-78` - `bash test/run.sh` → all 15 files pass (including 92 ruling tests) - `shellcheck lib/ruling.sh` - CI check-runs at this SHA: `test` and `self-guards` success No blocking findings. Non-blocking: none worth a follow-up this round.

kimi-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-23 16:02:54 +00:00

kimi-bot-andresmgsl (Migrated from github.com) left a comment

Approve — head a4918a5.

Reviewed the whole PR at this head against #73's acceptance criteria, and ran what could be run in a detached worktree at the head SHA.

Verified by execution

Full suite at the PR head: ruling.test.sh 92/0, issueflow-reconcile.test.sh 93/0, labels-reconcile.test.sh 91/0, and every other file green except the package-json/node cases in changelog-armed, drill-recorded, facts, version (9 failures total). Those same 9 fail identically on the merge base (f6797d0) in this environment — no node/jq installed here (I supplied a static jq to run the suite at all) — so they are environmental, not PR-caused. The failing cases are untouched by this diff.

Acceptance criteria walk

Malformed escalation → exactly one comment naming the missing labels and linking the escalation: proven by the fixture probes (items 15, 21) — one comment across two sweeps, names **Recommend:**, links https://x/esc15, quotes the BUILDER.md template location.
Conforming comment, including bold labels → nothing: item 10 probe uses $TPL_BOLD and asserts zero posts; the pure checks cover bold, <details> folds, and leading whitespace.
Bare flag → bare comment, no shape comment: the else in reconcile_ruling makes bare stop before the shape/rung block, and the probe greps the posted bare comment for the absence of shape/rung markers.
12h/24h rungs addressed to the flag-setter, naming the Default: state; 24h names triage's past-24h authority: items 16–18 probes, including the sweep-first-observes-past-24h case firing only the 24h comment.
Rungs don't reset on activity while the 7-day nudge does: item 16 is 13h in with activity 60s old — rung fires, nudge does not; both halves in the same test file as required.
Once-per-episode, re-flag re-comments: items 17 (cron walk 13h→25h, never a third) and 19 (old-episode rung markers don't stick to the re-flag).
No label mutation: the $TMP/edits probe and the mutation-name sweep now span the new paths; no reconciler file was edited, confirming both surfaces inherit the shared library unchanged (#50 D9).
Unreadable timeline/comments → no verdict, nothing posted: items 14 and 20, plus the undecodable-body branch in the orchestrator logs and skips rather than judging.

Code notes (non-blocking)

The base64-in-TSV carriage keeps the file line-oriented as the issue specified, and decode failures degrade to "unmarked"/"skip" — the safe direction on both idempotency and verdicts.
ruling_default_decision reads only the Default: line and never gates a rung on it — matches D14 exactly.
I could not run shellcheck here (not installed); the tests are the gate I executed.

The last criterion ("whole suite green on the merge SHA") is still unchecked in the PR body — I ran the suite at the head myself and the only reds are the pre-existing node-dependent ones above, so I am satisfied; the merge-SHA run remains the release flow's to confirm.

**Approve** — head a4918a5. Reviewed the whole PR at this head against #73's acceptance criteria, and ran what could be run in a detached worktree at the head SHA. **Verified by execution** - Full suite at the PR head: `ruling.test.sh` 92/0, `issueflow-reconcile.test.sh` 93/0, `labels-reconcile.test.sh` 91/0, and every other file green except the `package-json`/node cases in `changelog-armed`, `drill-recorded`, `facts`, `version` (9 failures total). Those same 9 fail identically on the merge base (f6797d0) in this environment — no `node`/`jq` installed here (I supplied a static `jq` to run the suite at all) — so they are environmental, not PR-caused. The failing cases are untouched by this diff. **Acceptance criteria walk** - Malformed escalation → exactly one comment naming the missing labels and linking the escalation: proven by the fixture probes (items 15, 21) — one comment across two sweeps, names `**Recommend:**`, links `https://x/esc15`, quotes the BUILDER.md template location. - Conforming comment, including bold labels → nothing: item 10 probe uses `$TPL_BOLD` and asserts zero posts; the pure checks cover bold, `<details>` folds, and leading whitespace. - Bare flag → bare comment, no shape comment: the `else` in `reconcile_ruling` makes bare stop before the shape/rung block, and the probe greps the posted bare comment for the absence of shape/rung markers. - 12h/24h rungs addressed to the flag-setter, naming the `Default:` state; 24h names triage's past-24h authority: items 16–18 probes, including the sweep-first-observes-past-24h case firing only the 24h comment. - Rungs don't reset on activity while the 7-day nudge does: item 16 is 13h in with activity 60s old — rung fires, nudge does not; both halves in the same test file as required. - Once-per-episode, re-flag re-comments: items 17 (cron walk 13h→25h, never a third) and 19 (old-episode rung markers don't stick to the re-flag). - No label mutation: the `$TMP/edits` probe and the mutation-name sweep now span the new paths; no reconciler file was edited, confirming both surfaces inherit the shared library unchanged (#50 D9). - Unreadable timeline/comments → no verdict, nothing posted: items 14 and 20, plus the undecodable-body branch in the orchestrator logs and skips rather than judging. **Code notes (non-blocking)** - The base64-in-TSV carriage keeps the file line-oriented as the issue specified, and decode failures degrade to "unmarked"/"skip" — the safe direction on both idempotency and verdicts. - `ruling_default_decision` reads only the `Default:` line and never gates a rung on it — matches D14 exactly. - I could not run `shellcheck` here (not installed); the tests are the gate I executed. The last criterion ("whole suite green on the merge SHA") is still unchecked in the PR body — I ran the suite at the head myself and the only reds are the pre-existing node-dependent ones above, so I am satisfied; the merge-SHA run remains the release flow's to confirm.