Skip to content

docs(hotfix): document orphan self-heal, correct stale reserved-shape comments, add callbacks matrix row#425

Merged
joshua-temple merged 2 commits into
mainfrom
docs/hotfix-selfheal-and-comments
Jul 1, 2026
Merged

docs(hotfix): document orphan self-heal, correct stale reserved-shape comments, add callbacks matrix row#425
joshua-temple merged 2 commits into
mainfrom
docs/hotfix-selfheal-and-comments

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

What

Final part of #411. Three code-verified items:

  1. Hotfix orphan self-heal docs (workflows.md): a "Reconciling a stale env branch" subsection documenting that the plan reconciles env/ against the recorded state SHA (absent -> create; matching -> untouched; drifted -> self-heal or fail-closed), that an interrupted run's orphan tip is force-reset to the recorded SHA, and the two-condition gate: reset fires ONLY when the env is not diverged AND the single-flight check (via --repo owner/repo) found no open hotfix PR matching either the cascade-hotfix or cascade-hotfix-conflict label. Notes --dry-run plans-but-does-not-reset, and that without --repo the self-heal cannot fire. Verified against internal/hotfix chain.go/plan.go/command.go/lifecycle.go.

  2. Corrected stale reserved-shape comments in internal/config/types.go, per-field verified against the generator:

    • Secrets, Permissions: emitted into the callback caller job (writeSecretsBlock / writeCallbackPermissions) -> now documented as wired into generation.
    • RunsOn, Concurrency: NOT emitted; validated-against and rejected on reusable-workflow callbacks -> comment now states parse/validation only, never emitted.
    • ExternalDeployConfig: left untouched (its comment is genuinely accurate; external.go hardcodes secrets: inherit and emits none of the four fields).
  3. coverage-matrix.md: added the missing Topologies row for cascade-example-callbacks (the 11th fleet repo the tip already counts), mapped to the existing act scenarios orchestrate/secrets-opt-in and orchestrate/callback-permissions-oidc.

Verification

go build clean; go vet ./internal/config clean (types.go change is comment-only); markdown well-formed; guardrails clean.

Maintainer note (out of scope, flagging): coverage-matrix's "Last validated" tip still says v0.5.1.

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
…e row

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple joshua-temple merged commit cabb104 into main Jul 1, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant