Repository navigation
Description
Story
As the org,
I want the compliance audit to check and remediate the derived <id>:hands-off label family, not just the seven fixed labels,
so that a repo missing a persona opt-out label is reported and fixed automatically instead of being discovered by hand.
Filed from combsmith/.github-private#1644 (epic combsmith/.github-private#1643). No new standard is needed — standards/github-settings.md §"Labels — Standard Set" already mandates both the fixed set and the derived family. What is missing is the check and the fix.
The gap (verified 2026-09-15)
check_labels() in scripts/compliance-audit.sh iterates REQUIRED_LABEL_SPECS — seven hardcoded entries (security, dependencies, scorecard, bug, enhancement, documentation, in-progress). The derived family is never consulted. The only opt-out label the audit knows is the DEV_LEAD_HANDS_OFF_LABEL special case, which exists so a finding issue can carry it — not as a compliance check.
scripts/compliance-remediate.sh keeps a second, independent hardcoded copy of the same seven labels (LABEL_COLORS / LABEL_DESCS), so even once the audit reports a missing persona label, the remediator cannot create it.
Consequence, from the labels API on 2026-09-15 — nine personas exist, so nine <id>:hands-off labels are expected per repo:
| Repo | <id>:hands-off labels |
|---|---|
.github, .github-private, bmad-bgreat-suite, TalkTerm |
9 |
markets, ContentTwin, repo-template, broodly, incubator |
1 (dev-lead:hands-off only) |
The weekly audit (compliance-audit-and-improvement.yml) ran green on 2026-09-11 with five repos in that state and filed no finding, because no check covers the family.
Why the labels are absent differs per repo, and is mostly tracked elsewhere:
ContentTwin,repo-template,broodly,incubatorhave noapply-repo-settingscaller stub yet → #1045 Step D: add apply-repo-settings.yml to DEPLOYABLE_WORKFLOWS (Step C done — v1-stable exists) #1128.markets' workflow isdisabled_manuallyand its last run (2026-08-31) failed for a missingGH_TOKEN_ADMIN. Being disabled looks like a deliberate human choice — report it, do not re-enable it.TalkTermself-healed on 2026-09-14 (run34844937654) once the check-suites 403 of .github-private#1209 was fixed. Before that it failed weekly, having aborted mid-run.
That last case is the reason for AC #5: the applier should not lose label provisioning because an unrelated settings step failed first.
Acceptance Criteria
check_labels()checks the derived<id>:hands-offfamily in addition to the fixed set, deriving it from the persona manifests exactly asapply-repo-settings.sh(persona_opt_out_label_configs()) does. Adding a persona must require no edit to any label list — the constraint from Provision <id>:hands-off labels so persona opt-out actually works #756.- One source of truth. The audit and the remediator must not hold two hardcoded label tables. Extract the fixed set and the derivation into a shared helper both source.
- Fail closed. If the manifests cannot be read, emit an error or finding. Never treat an unreadable manifest list as "no persona labels required" — mirror the guard
apply-repo-settings.shalready has for a failed derivation. - Remediation creates the missing labels through the existing idempotent path. The read-only default stands (compliance-audit.sh closes live findings: fail-open closure, umbrella title mismatch, no execution guard #1036 AC Add workflow, environment, and orchestration guidance #4): no mutation without
--apply, and--dry-runreports without mutating. - A failing settings step must not skip label provisioning. Check the step ordering and failure handling in
apply-repo-settings.sh: if a hard failure (e.g. the check-suites PATCH) can abort the run beforeapply_labels(), decouple them so labels are still applied and the run still reports the failure. If ordering already guarantees this, say so in the PR with the evidence and treat the AC as met. - Before/after evidence in the PR description: the
<id>:hands-offcount per repo from the labels API, for all nine repos. shellcheck --severity=warning -xclean. Tests in the existing bats suite cover: a repo missing one persona label produces a finding; unreadable manifests fail closed; a compliant repo produces none.
Out of scope
- Deploying the caller stub to the four repos that lack it — #1045 Step D: add apply-repo-settings.yml to DEPLOYABLE_WORKFLOWS (Step C done — v1-stable exists) #1128.
- Re-enabling
markets' workflow or provisioning itsGH_TOKEN_ADMINsecret. Report it; it needs a maintainer decision.
Budget guard
- Shared derivation helper + the audit check + tests (AC Addressing PR comments #1–Add coding standards & principles section to AGENTS.md #3, docs: document branch protection rules, rulesets, and auto-merge policy #7). This is the commit that matters.
- Wire the remediator to the shared list (AC Add workflow, environment, and orchestration guidance #4).
- The applier decoupling (AC Add stacked PR strategy and Epic-level workflow guidance #5) and the evidence table (AC feat: add Structured Logging and CQRS standards #6).
If you run low on budget, stop after any step with a green PR and file the rest as a follow-up. Do not attempt all three and time out.
References
- [qa-lead S1] Provision <id>:hands-off labels across the fleet — the opt-out is inert where the persona actually runs .github-private#1644, Epic: qa-lead — close the gap between the declared persona and the served one .github-private#1643 (epic)
standards/github-settings.md§"Labels — Standard Set" (the derived family)scripts/compliance-audit.sh(check_labels,REQUIRED_LABEL_SPECS),scripts/compliance-remediate.sh(LABEL_COLORS/LABEL_DESCS),scripts/apply-repo-settings.sh(persona_opt_out_label_configs)- Provision <id>:hands-off labels so persona opt-out actually works #756 (derive-don't-enumerate), #1045 Step D: add apply-repo-settings.yml to DEPLOYABLE_WORKFLOWS (Step C done — v1-stable exists) #1128 (stub deployment), compliance-audit.sh closes live findings: fail-open closure, umbrella title mismatch, no execution guard #1036 (read-only default)
Activity
don-petry commentedon Sep 16, 2026
Dev-Lead Implementation Plan
Issue: #1139 — compliance-audit ignores the derived
<id>:hands-offlabel family — missing persona opt-out labels are never reported or remediatedScope
Extract the fixed label set + the persona opt-out derivation into one shared helper that the audit, remediator, and applier all source; teach
check_labels()to check the derived<id>:hands-offfamily (fail-closed on unreadable manifests); wire the remediator to the shared list; verify the applier already decouples label provisioning from a failing settings step.Implementation Checklist
scripts/lib/labels.sh— new shared source of truth:STANDARD_LABEL_SPECS(fixed 7) +persona_opt_out_label_configs()(moved from applier) +std_label_spec()lookup helper + persona manifest config (PERSONA_MANIFEST_REPO/REF,PERSONA_OPT_OUT_COLOR)scripts/apply-repo-settings.sh— source the lib; drop the now-shared copies (persona_opt_out_label_configs, manifest vars, color) and buildapply_labels' fixed set fromSTANDARD_LABEL_SPECS; keep its existing cache wrapper untouchedscripts/compliance-audit.sh— source the lib; replaceREQUIRED_LABEL_SPECS; rewritecheck_labels()to check the fixed set + the derived persona family, failing closed with an error finding when derivation failsscripts/compliance-remediate.sh— source the lib; dropLABEL_COLORS/LABEL_DESCS; look up color/desc viastd_label_spec()(fixed set + derived family) so a missing persona label can be createdapply-repo-settings.shstep ordering; confirmapply_labelscannot be aborted by an earlier failing step (already guaranteed byapply_repo'sstep || FAILED_STEPS+=(...)— apply-repo-settings.sh aborts before the ruleset self-heal — 30/30 CI runs failed, pr-quality convergence has never executed #1038); document evidence in PR<id>:hands-offcount per repo (all nine) in the PR descriptionTests to Write
test/scripts/compliance-audit/labels-hands-off-family.bats— a repo missing one persona label produces amissing-label-<id>:hands-offfinding; unreadable manifests fail closed with an error finding; a compliant repo (all fixed + derived present) produces nonetest/scripts/compliance-remediate/labels-derived.bats— remediator resolves color/desc for a derived<id>:hands-offlabel from the shared list; dry-run mutates nothingtest/scripts/apply-repo-settings/apply-repo-settings.batsmust stay green after the lib extractionTest Command
bats --print-output-on-failure test/scripts/compliance-audit/ test/scripts/apply-repo-settings/ test/scripts/compliance-remediate/+shellcheck --severity=warning -x scripts/*.sh scripts/lib/*.shdon-petry commentedon Sep 16, 2026
Dev-Lead: Progress (in progress — not yet durable)
Plan Execution (intended)
scripts/lib/labels.shholds the fixed set (STANDARD_LABEL_SPECS), the derived-family derivation (persona_opt_out_label_configs, moved verbatim from the applier), and astd_label_spec()lookup. The audit, remediator, and applier all source it; the three separate hardcoded label tables are gone (AC#2).check_labels()now checks the fixed set and the derived<id>:hands-offfamily, derived from the persona manifests exactly asapply-repo-settings.shdoes (AC#1). It fails closed: an unreadable/garbled manifest listing emits apersona-opt-out-derivation-failederror finding rather than reading as "no persona labels required" (AC#3).remediate_label()resolves colour+description viastd_label_spec()(fixed set + derived family), so a missing persona label can now be created through the existing idempotent--forcepath; read-only/--dry-rundefault preserved (AC#4).apply_repo()already runsapply_labelssecond (beforeapply_check_suite_prefs, last) and guards every step with|| FAILED_STEPS+=(...), so a failing settings/check-suites step cannot abort label provisioning (the apply-repo-settings.sh aborts before the ruleset self-heal — 30/30 CI runs failed, pr-quality convergence has never executed #1038 fix). Existingapply-repo-settings.batstests already lock this in ("apply_repo runs every step even when an EARLY step fails"). Evidence to go in the PR body.AC#6 — before evidence (
<id>:hands-offcount per repo, labels API, 2026-09-16)Expected family size = 9 (nine personas: business-analyst, dev-lead, devops-lead, pr-review, qa-lead, scrum-master, security-lead, solution-architect, sre-lead).
.githubmarkets.github-privateContentTwinbmad-bgreat-suiterepo-templateTalkTermbroodlyincubatorMatches the issue's 2026-09-15 table. After this change the audit reports 8
missing-label-<id>:hands-offfindings on each of the five 1-label repos (family now checked); the remediator/applier can create them. "After" counts follow once the applier/remediator run on the fleet (out of scope for this script-only PR; markets stays disabled per the issue — reported, not re-enabled).Local check output (provisional — not the pushed run)
Files touched (this workspace, not yet pushed)
scripts/lib/labels.sh(new): shared label source of truth +std_label_spec().scripts/compliance-audit.sh: source the lib; dropREQUIRED_LABEL_SPECS;check_labels()checks the derived family + fails closed.scripts/compliance-remediate.sh: source the lib; dropLABEL_COLORS/LABEL_DESCS;remediate_label()usesstd_label_spec().scripts/apply-repo-settings.sh: source the lib; drop the now-shared derivation + persona vars; buildapply_labelsfixed set fromSTANDARD_LABEL_SPECS(its cache untouched).test/scripts/compliance-audit/labels-hands-off-family.bats(new): missing persona label → finding; unreadable manifests → fail closed; compliant repo → none.test/scripts/compliance-remediate/labels-derived.bats(new): remediator creates a derived label;std_label_speclookup; fail-closed derivation.Notes
don-petry commentedon Sep 16, 2026
Dev-Lead: Implementation Complete — PR #1140
The implementation for issue #1139 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.
421b31a234821f01f99a1e49a3a3a603c010c1e5Review happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.
feat: implement issue #1139 — compliance-audit ignores the derived <i…