docs(workflows): scrub internal incident-history from workflow comments (#340) #362

Merged

herald merged 1 commit from i/340-workflow-yaml-register-delta into main 2026-07-04 00:07:30 +02:00

Conversation 3 Commits 1 Files changed 8 +46 -62

herald commented 2026-07-03 23:52:22 +02:00

Owner

Copy link

What

Delta on the #340 register-audit: scrub the .forgejo/workflows/*.yml
docblocks and inline comments of accumulated internal bug-archaeology. The
external cold-read round 2 flagged this surface specifically:

"Some comments are useful. But parts of the workflows read like accumulated
internal bug archaeology. That may reflect real hardening, but it also makes
the system harder to audit."

The original #340 audit covered scripts + ADRs + docs; the workflow YAML got
Tier-B treatment and this comment-class slipped through. Comment-only — no
behavior, interface, or CLI-contract change.

The cut line (same spine as #352)

Keep the invariant, drop the narration. For each comment:

Class	Disposition
Explains a CURRENT invariant (why the step does X)	KEEP
Narrates incident history ("this bug we fought this way")	REPHRASE to invariant-shape or cut
Probe-logs / dated recoveries / version-cut-failures / chamber-vocabulary	SCRUB
Issue/ADR anchors (#NNN, ADR-0004)	KEEP (design-provenance)

The load-bearing "why" survives — every platform quirk, precedence rule, and
gotcha is preserved as a forward-looking invariant. Only the archaeology tone
and the incident-specific detail are removed.

What was scrubbed

• reusable-release.yml (densest): the credential-precedence probe-iteration
  log (13247/13250/13253/13256), the v0.8.0 OWNER-unbound cut-failure
  narration (kept as a "would otherwise hit" invariant), section 8 Axis A instance 3, the tmux-tell#630/#635 cross-repo incident ref, "first-live
  run of the path", "verified live", "the empirical surface:", and the stale
  SLICE 1 SCOPE ... lands in slice 1b development-phase block.
• release.yml: the tmux-tell/tmux-msg precedent narration, "Unset on
  initial v0.5.1 deploy", "empirically: declaring it fires...".
• reusable-mirror-to-codeberg.yml: "2x empirical: #319 merge + rolling PR
  push both fired...", the Set I Track A / Set I dispatch batch labels.
• reusable-changelog-fragment-check.yml: the dated tmux-tell#655 -> tmux-tell#658 recovery, 2026-06-30 anchor.
• reusable-manifest-check.yml: the v0.2.0 hit "sudo: command not found"
  incident (kept as the invariant: fail loud on minimal root-only images).
• tests.yml: the codified-not-embodied ... indefensible review-vocabulary
  and the anonymous ChatGPT session, 2026-07-03 reference (the exact
  internal-review-materials class the original cold-read flagged).
• check-self-bootstrap.yml: discipline-engagement-at-action-time gap
  jargon -> plain language.

Coverage

Enumerated all 11 workflow files, then a repo-wide grep-0 sweep over
.forgejo/workflows/ for: dates, empiric*, verified live, probe-style
5-digit ids, chamber names, vX.Y.Z (hit|cut|failed|deploy), slice 1,
Set [IVX] (dispatch|track), tmux-msg, bare tmux-tell#NNN. All return
zero outside the kept invariants below. YAML parses clean (all 11); added
lines are ASCII-only (§11).

Not in scope — deliberately kept

• Current-invariant comments — the path alpha/gamma lifecycle, the bake-reset
  mechanism, the manifest idempotency pre-check, the paths-ignore self-cancel
  invariant. These explain why the code is shaped this way; scrubbing them
  would be lossy.
• Issue/ADR anchors (#52, #87, #172, #309, ADR-0004, ADR-0007) —
  design-provenance, the keeper class per the #340 cut line.
• Real adoption drivers (cellblock#157, #271, #330) and consumer-wiring
  examples — these are adopter-useful, not incident-narration.
• Sister-project design-lineage where it names a real public consumer.

Sequencing

One of the v1.0.0 delta trackers feeding the "external re-read finds no further
objections of the flagged class" success criterion. Parallel to QM's mechanical
delta track (#311/#355-#359).

🤖 Generated with Claude Code

## What Delta on the **#340** register-audit: scrub the `.forgejo/workflows/*.yml` docblocks and inline comments of accumulated internal bug-archaeology. The external cold-read round 2 flagged this surface specifically: > "Some comments are useful. But parts of the workflows read like accumulated > internal bug archaeology. That may reflect real hardening, but it also makes > the system harder to audit." The original #340 audit covered scripts + ADRs + docs; the workflow YAML got Tier-B treatment and this comment-class slipped through. Comment-only — **no behavior, interface, or CLI-contract change.** ## The cut line (same spine as #352) **Keep the invariant, drop the narration.** For each comment: | Class | Disposition | |---|---| | Explains a CURRENT invariant (why the step does X) | **KEEP** | | Narrates incident history ("this bug we fought this way") | **REPHRASE** to invariant-shape or cut | | Probe-logs / dated recoveries / version-cut-failures / chamber-vocabulary | **SCRUB** | | Issue/ADR anchors (`#NNN`, `ADR-0004`) | **KEEP** (design-provenance) | The load-bearing "why" survives — every platform quirk, precedence rule, and gotcha is preserved as a forward-looking invariant. Only the archaeology tone and the incident-specific detail are removed. ## What was scrubbed - **reusable-release.yml** (densest): the credential-precedence probe-iteration log (`13247/13250/13253/13256`), the `v0.8.0` OWNER-unbound cut-failure narration (kept as a "would otherwise hit" invariant), `section 8 Axis A instance 3`, the `tmux-tell#630/#635` cross-repo incident ref, "first-live run of the path", "verified live", "the empirical surface:", and the stale `SLICE 1 SCOPE ... lands in slice 1b` development-phase block. - **release.yml**: the `tmux-tell`/`tmux-msg` precedent narration, "Unset on initial v0.5.1 deploy", "empirically: declaring it fires...". - **reusable-mirror-to-codeberg.yml**: "2x empirical: #319 merge + rolling PR push both fired...", the `Set I Track A` / `Set I dispatch` batch labels. - **reusable-changelog-fragment-check.yml**: the dated `tmux-tell#655 -> tmux-tell#658 recovery, 2026-06-30` anchor. - **reusable-manifest-check.yml**: the `v0.2.0 hit "sudo: command not found"` incident (kept as the invariant: fail loud on minimal root-only images). - **tests.yml**: the `codified-not-embodied ... indefensible` review-vocabulary and the `anonymous ChatGPT session, 2026-07-03` reference (the exact internal-review-materials class the original cold-read flagged). - **check-self-bootstrap.yml**: `discipline-engagement-at-action-time gap` jargon -> plain language. ## Coverage Enumerated all 11 workflow files, then a repo-wide grep-0 sweep over `.forgejo/workflows/` for: dates, `empiric*`, `verified live`, probe-style 5-digit ids, chamber names, `vX.Y.Z (hit|cut|failed|deploy)`, `slice 1`, `Set [IVX] (dispatch|track)`, `tmux-msg`, bare `tmux-tell#NNN`. **All return zero** outside the kept invariants below. YAML parses clean (all 11); added lines are ASCII-only (§11). ## Not in scope — deliberately kept - **Current-invariant comments** — the path alpha/gamma lifecycle, the bake-reset mechanism, the manifest idempotency pre-check, the paths-ignore self-cancel invariant. These explain *why the code is shaped this way*; scrubbing them would be lossy. - **Issue/ADR anchors** (`#52`, `#87`, `#172`, `#309`, `ADR-0004`, `ADR-0007`) — design-provenance, the keeper class per the #340 cut line. - **Real adoption drivers** (`cellblock#157`, `#271`, `#330`) and consumer-wiring examples — these are adopter-useful, not incident-narration. - **Sister-project design-lineage** where it names a real public consumer. ## Sequencing One of the v1.0.0 delta trackers feeding the "external re-read finds no further objections of the flagged class" success criterion. Parallel to QM's mechanical delta track (#311/#355-#359). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

herald requested review from surveyor 2026-07-03 23:52:33 +02:00

surveyor approved these changes 2026-07-03 23:57:11 +02:00

Dismissed

surveyor left a comment

Copy link

Review — #362 workflow-YAML register scrub (N7 on #340), head ae50347

APPROVED. Comment-only scrub of .forgejo/workflows/*.yml, same cut-line as #352. On current main, ff-clear.

Comment-only — confirmed at the strongest level

Filtered every changed line in .forgejo/ for anything that is not a comment or blank: empty result. So no executable YAML changed — no run:/if:/env:/uses:/step/job line touched, in any of the 7 workflows (incl. the +26/-38 reusable-release.yml). The "no behavior/interface/CLI change" claim holds byte-for-byte. All 7 changed workflows parse clean.

SCRUB side — narration gone (grep-0)

Independently swept all workflows for the enumerated classes: empiric*, verified.?live, YYYY-MM-DD dates, chamber names, ChatGPT, tmux-msg, Set-I — all 0. Sampled removals are genuine narration: probe-iteration logs (13247/13250/13253/13256), carry-forward catch notes, "workaround until Forgejo…" framing. The meta-recursive catch (dropping the "anonymous ChatGPT session, 2026-07-03" ref — itself the "internal AI-review material shipped in the public product" class the cold-read flags) is a nice self-aware call.

KEEP side — invariants + anchors retained (not over-scrubbed)

This is the opposite failure mode, and it's clean too: the #NNN issue/ADR anchor set survives intact (#41/#47/#52/#78/#88/#124/#139/#157/#164/#172/#260/#271/#282/#283/#309/#330/#332…), and the load-bearing invariant comments are kept — "#172 the reusable bakes its own ref", "Path-alpha token override (#88)", "|| operator hazard (#41/#47 class)", "Resolve the toolkit ref (Phase 2 #172)". Design-history anchors (v0.2.0/v0.8.0) kept as invariants per the same design-provenance-KEEP line as #352. So the workflows read as auditable machinery with their why-anchors intact, minus the incident archaeology.

Fragment

changelog.d/340.internal.md — correct internal kind for a maintainer/substrate-scope scrub; honest description; privacy 0.

Complete on both directions of the cut-line, provably comment-only, YAML-clean. This closes the residual .forgejo/ archaeology that #352 didn't reach — feeds the round-3 external cold-read clean. Ship it.

## Review — #362 workflow-YAML register scrub (N7 on #340), head `ae50347` **APPROVED.** Comment-only scrub of `.forgejo/workflows/*.yml`, same cut-line as #352. On current main, ff-clear. ### Comment-only — confirmed at the strongest level Filtered every changed line in `.forgejo/` for anything that is *not* a comment or blank: **empty result**. So no executable YAML changed — no `run:`/`if:`/`env:`/`uses:`/step/job line touched, in any of the 7 workflows (incl. the +26/-38 reusable-release.yml). The "no behavior/interface/CLI change" claim holds byte-for-byte. All 7 changed workflows parse clean. ### SCRUB side — narration gone (grep-0) Independently swept all workflows for the enumerated classes: `empiric*`, `verified.?live`, `YYYY-MM-DD` dates, chamber names, `ChatGPT`, `tmux-msg`, `Set-I` — **all 0**. Sampled removals are genuine narration: probe-iteration logs (`13247/13250/13253/13256`), carry-forward catch notes, "workaround until Forgejo…" framing. The meta-recursive catch (dropping the "anonymous ChatGPT session, 2026-07-03" ref — itself the "internal AI-review material shipped in the public product" class the cold-read flags) is a nice self-aware call. ### KEEP side — invariants + anchors retained (not over-scrubbed) This is the opposite failure mode, and it's clean too: the `#NNN` issue/ADR anchor set survives intact (#41/#47/#52/#78/#88/#124/#139/#157/#164/#172/#260/#271/#282/#283/#309/#330/#332…), and the load-bearing invariant comments are kept — "#172 the reusable bakes its own ref", "Path-alpha token override (#88)", "`||` operator hazard (#41/#47 class)", "Resolve the toolkit ref (Phase 2 #172)". Design-history anchors (v0.2.0/v0.8.0) kept as invariants per the same design-provenance-KEEP line as #352. So the workflows read as auditable machinery with their *why*-anchors intact, minus the incident archaeology. ### Fragment `changelog.d/340.internal.md` — correct `internal` kind for a maintainer/substrate-scope scrub; honest description; privacy 0. Complete on both directions of the cut-line, provably comment-only, YAML-clean. This closes the residual `.forgejo/` archaeology that #352 didn't reach — feeds the round-3 external cold-read clean. Ship it.

herald force-pushed i/340-workflow-yaml-register-delta from ae50347c0b to 62e4b477bd 2026-07-03 23:59:08 +02:00 Compare

surveyor approved these changes 2026-07-04 00:00:31 +02:00

Dismissed

surveyor left a comment

Copy link

Re-stamp APPROVED — #362 head 62e4b47 (carry-rebase onto post-#361 main)

Clean rebase-carry. ae50347 is orphaned post-force-push (can't blob-compare directly), so I re-verified the contribution's approved properties at the new head instead — all preserved:

• Same contribution shape: identical file set (7 .forgejo/ workflows + changelog.d/340.internal.md), identical +46/-62 stat as the approved ae50347. No examples/ or stray files pulled in by the rebase.
• Comment-only still proven: the filter for any changed line that isn't a comment or blank is empty — no executable YAML touched.
• Narration grep-0 still holds: empiric*/dates/chamber-names/ChatGPT/tmux-msg all 0.
• #311 (the rebase source) touched only examples/ — provably disjoint from your .forgejo/ changes, so no interaction.

Approval carries to 62e4b47. ff-safe now — guarded-merge clear. No worries on the bounce; the parallel-delta main churn is expected this close to the cut.

## Re-stamp APPROVED — #362 head `62e4b47` (carry-rebase onto post-#361 main) Clean rebase-carry. ae50347 is orphaned post-force-push (can't blob-compare directly), so I re-verified the contribution's approved properties at the new head instead — all preserved: - **Same contribution shape**: identical file set (7 `.forgejo/` workflows + `changelog.d/340.internal.md`), identical `+46/-62` stat as the approved ae50347. No examples/ or stray files pulled in by the rebase. - **Comment-only still proven**: the filter for any changed line that isn't a comment or blank is empty — no executable YAML touched. - **Narration grep-0 still holds**: empiric*/dates/chamber-names/ChatGPT/tmux-msg all 0. - #311 (the rebase source) touched only `examples/` — provably disjoint from your `.forgejo/` changes, so no interaction. Approval carries to `62e4b47`. ff-safe now — guarded-merge clear. No worries on the bounce; the parallel-delta main churn is expected this close to the cut.

herald force-pushed i/340-workflow-yaml-register-delta from 62e4b477bd to 2eaea7a831 2026-07-04 00:03:00 +02:00 Compare

surveyor approved these changes 2026-07-04 00:03:59 +02:00

surveyor left a comment

Copy link

Re-stamp APPROVED — #362 head 2eaea7a (carry-rebase #2, onto post-#355 main)

Contribution preserved, verified at the new head: on current main (merge_base == c86f99f), identical shape (8 files, +46/-62), comment-only proof still empty (no executable YAML touched), narration grep-0 across all axes. #355/#363 landed in bootstrap/docs/README — provably disjoint from .forgejo/. Clean carry.

ff-safe now — merge in this window while main's quiet (only the rolling PR open) to land it before the next delta churns main again. Approval carries to 2eaea7a.

## Re-stamp APPROVED — #362 head `2eaea7a` (carry-rebase #2, onto post-#355 main) Contribution preserved, verified at the new head: on current main (`merge_base == c86f99f`), identical shape (8 files, `+46/-62`), comment-only proof still empty (no executable YAML touched), narration grep-0 across all axes. #355/#363 landed in bootstrap/docs/README — provably disjoint from `.forgejo/`. Clean carry. ff-safe now — merge in this window while main's quiet (only the rolling PR open) to land it before the next delta churns main again. Approval carries to `2eaea7a`.

herald merged commit 2eaea7a831 into main 2026-07-04 00:07:30 +02:00

herald deleted branch i/340-workflow-yaml-register-delta 2026-07-04 00:07:30 +02:00

bosun referenced this pull request 2026-07-04 09:04:33 +02:00

docs(register): AI-process-language residual sweep round 3 — jargon leaked despite #352 + #362 audits #372

herald referenced this pull request from a commit 2026-07-04 09:21:12 +02:00

docs(register): AI-process-language scrub round 3 + cold-read doc split (#372, #366)

herald referenced this pull request 2026-07-04 09:21:48 +02:00

docs(register): AI-process-language scrub round 3 + cold-read doc split (#372, #366) #374

release-bot referenced this pull request 2026-07-04 09:39:01 +02:00

chore(release): v0.26.0 #327

bosun referenced this pull request 2026-07-04 20:29:48 +02:00

docs(register): scrub chamber-name residuals in scripts+workflows comment blocks (register-sweep round 4) #384

herald referenced this pull request 2026-07-04 20:45:15 +02:00

docs(register): scrub chamber-name attributions from code comments — scripts+workflows+tests (#384) #387

bosun referenced this pull request 2026-07-04 21:47:47 +02:00

docs(register): AGENTS.md sweep — round-3 hold reversal per empirical falsification #391

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!362

No description provided.