From 7c7b98d7e9713b29c26216aecd0f333e6cb49039 Mon Sep 17 00:00:00 2001 From: Andrew Shoell Date: Wed, 8 Apr 2026 21:39:32 -0600 Subject: [PATCH 1/4] chore: migrate workflow helper scripts to scripts/workflows --- .github/workflows/action-validator.yaml | 2 +- .github/workflows/agents-validate.yaml | 6 +++--- .github/workflows/dependabot-autobump.yaml | 4 ++-- .github/workflows/docs-bump.yaml | 4 ++-- CHANGELOG.md | 8 ++++++++ bsctl/static/resources/constants.yaml | 2 +- docs/plans/bsctl-codeql-decommission-plan.md | 8 ++++---- resources/version.yaml | 2 +- .../action-validator_check-actions_lint-actions.sh | 6 +++--- .../agents-validate_agents-instructions-check.sh | 0 .../workflows/dependabot-autobump_bump-version.sh | 0 .../workflows/dependabot-autobump_update-changelog.sh | 0 .../workflows/docs-bump_docs-bump_CHANGELOG-bump.sh | 0 .../workflows/docs-bump_docs-bump_version-bump.sh | 0 14 files changed, 25 insertions(+), 17 deletions(-) rename {bsctl/scripts => scripts}/workflows/action-validator_check-actions_lint-actions.sh (50%) rename {bsctl/scripts => scripts}/workflows/agents-validate_agents-instructions-check.sh (100%) rename {bsctl/scripts => scripts}/workflows/dependabot-autobump_bump-version.sh (100%) rename {bsctl/scripts => scripts}/workflows/dependabot-autobump_update-changelog.sh (100%) rename {bsctl/scripts => scripts}/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh (100%) rename {bsctl/scripts => scripts}/workflows/docs-bump_docs-bump_version-bump.sh (100%) diff --git a/.github/workflows/action-validator.yaml b/.github/workflows/action-validator.yaml index 1a6c8dee..95c074d9 100644 --- a/.github/workflows/action-validator.yaml +++ b/.github/workflows/action-validator.yaml @@ -30,4 +30,4 @@ jobs: action-validator 0.5.1 - name: Lint Actions - run: ./bsctl/scripts/workflows/action-validator_check-actions_lint-actions.sh + run: ./scripts/workflows/action-validator_check-actions_lint-actions.sh diff --git a/.github/workflows/agents-validate.yaml b/.github/workflows/agents-validate.yaml index 14a8fa04..ee5e246f 100644 --- a/.github/workflows/agents-validate.yaml +++ b/.github/workflows/agents-validate.yaml @@ -8,7 +8,7 @@ on: - "AGENTS.md" - ".agents/**" - ".github/workflows/agents-validate.yaml" - - "bsctl/scripts/workflows/agents-validate_agents-instructions-check.sh" + - "scripts/workflows/agents-validate_agents-instructions-check.sh" pull_request: branches: - main @@ -16,7 +16,7 @@ on: - "AGENTS.md" - ".agents/**" - ".github/workflows/agents-validate.yaml" - - "bsctl/scripts/workflows/agents-validate_agents-instructions-check.sh" + - "scripts/workflows/agents-validate_agents-instructions-check.sh" workflow_dispatch: defaults: @@ -36,4 +36,4 @@ jobs: uses: mikefarah/yq@v4 - name: Validate agent instructions and skills - run: ./bsctl/scripts/workflows/agents-validate_agents-instructions-check.sh + run: ./scripts/workflows/agents-validate_agents-instructions-check.sh diff --git a/.github/workflows/dependabot-autobump.yaml b/.github/workflows/dependabot-autobump.yaml index 930acca7..9d9c94e6 100644 --- a/.github/workflows/dependabot-autobump.yaml +++ b/.github/workflows/dependabot-autobump.yaml @@ -53,13 +53,13 @@ jobs: - name: Bump version if: steps.check_autobump.outputs.already_bumped == 'false' - run: ./bsctl/scripts/workflows/dependabot-autobump_bump-version.sh + run: ./scripts/workflows/dependabot-autobump_bump-version.sh - name: Update CHANGELOG if: steps.check_autobump.outputs.already_bumped == 'false' env: PR_TITLE: ${{ github.event.pull_request.title }} - run: ./bsctl/scripts/workflows/dependabot-autobump_update-changelog.sh + run: ./scripts/workflows/dependabot-autobump_update-changelog.sh - name: Check for changes if: steps.check_autobump.outputs.already_bumped == 'false' diff --git a/.github/workflows/docs-bump.yaml b/.github/workflows/docs-bump.yaml index 00181488..e8e3c9b7 100644 --- a/.github/workflows/docs-bump.yaml +++ b/.github/workflows/docs-bump.yaml @@ -19,7 +19,7 @@ jobs: uses: actions/checkout@v6 - name: Version Bump - run: ./bsctl/scripts/workflows/docs-bump_docs-bump_version-bump.sh + run: ./scripts/workflows/docs-bump_docs-bump_version-bump.sh - name: CHANGELOG Bump - run: ./bsctl/scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh + run: ./scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index ffabdf80..c32df459 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +--- +## [0.1.22] - 2026-04-09 + +### Changed + +- Migrated workflow helper scripts from `bsctl/scripts/workflows/` to `scripts/workflows/` and updated workflow call sites (`docs-bump`, `dependabot-autobump`, `action-validator`, and `agents-validate`). +- Updated #320 decommission planning docs to reflect completed script-path migration and the new neutral script location. + --- ## [0.1.21] - 2026-04-09 diff --git a/bsctl/static/resources/constants.yaml b/bsctl/static/resources/constants.yaml index 942dd411..2b272d20 100644 --- a/bsctl/static/resources/constants.yaml +++ b/bsctl/static/resources/constants.yaml @@ -1,2 +1,2 @@ # BasicSetupCliVersion - constant for semantic versioning -BasicSetupCliVersion: "0.1.21" +BasicSetupCliVersion: "0.1.22" diff --git a/docs/plans/bsctl-codeql-decommission-plan.md b/docs/plans/bsctl-codeql-decommission-plan.md index 5a70f3e0..b8ac8f8c 100644 --- a/docs/plans/bsctl-codeql-decommission-plan.md +++ b/docs/plans/bsctl-codeql-decommission-plan.md @@ -14,9 +14,9 @@ Retire remaining `bsctl` Go CLI and CodeQL dependencies without breaking release | Area | Current dependency | Why it exists today | Replacement target | Removal gate | | --- | --- | --- | --- | --- | | Release candidate workflow | `.github/workflows/release.yml` reads `resources/version.yaml` (legacy fallback to `bsctl/static/resources/constants.yaml` during transition) | Version source for candidate metadata | Complete cutover to root-level version source | Candidate workflow passes with no `bsctl` path usage | -| Docs bump workflow | `.github/workflows/docs-bump.yaml` invokes `bsctl/scripts/workflows/docs-bump_*` | Enforces version/changelog divergence and date checks | Promote scripts to root-level workflow scripts (or equivalent maintained path) | Docs-bump checks pass using replacement scripts | -| Dependabot autobump | `.github/workflows/dependabot-autobump.yaml` invokes `bsctl/scripts/workflows/dependabot-autobump_*` and stages `resources/version.yaml` (plus legacy constants during transition) | Automates patch bump + changelog update for dep PRs | Update to replacement version source + script paths | Dependabot autobump PR succeeds without `bsctl` references | -| Action validator and agents validate | Workflows call scripts in `bsctl/scripts/workflows/*` | Existing script organization | Relocate scripts to neutral location (for example `scripts/workflows/`) | Validation workflows remain green after path migration | +| Docs bump workflow | `.github/workflows/docs-bump.yaml` invokes `scripts/workflows/docs-bump_*` | Enforces version/changelog divergence and date checks | Keep scripts in root-level workflow script location | Docs-bump checks pass using replacement scripts | +| Dependabot autobump | `.github/workflows/dependabot-autobump.yaml` invokes `scripts/workflows/dependabot-autobump_*` and stages `resources/version.yaml` (plus legacy constants during transition) | Automates patch bump + changelog update for dep PRs | Keep script paths and finalize legacy-version cleanup later | Dependabot autobump PR succeeds without `bsctl` references | +| Action validator and agents validate | Workflows call scripts in `scripts/workflows/*` | Existing script organization | Keep scripts in neutral location | Validation workflows remain green after path migration | | Code scanning | `.github/workflows/codeql.yaml` scans Go | Security coverage for Go code under `bsctl/` | Re-scope/remove CodeQL after supported-language coverage decision | `bsctl` removal complete and security coverage documented | | Label automation | `.github/labeler.yaml` maps `bsctl/**/*` to change labels | Surfacing path-based impact in PRs | Replace with new paths or retire mapping if no longer needed | Label behavior remains correct after path removals | | Agent guidance and skills | `AGENTS.md`, `.agents/skills/*.md`, docs reference `resources/version.yaml` (legacy mention only for transition) | Instructions aligned with current version source | Update docs to new source-of-truth path | No remaining mandatory guidance references to retired path | @@ -31,7 +31,7 @@ Retire remaining `bsctl` Go CLI and CodeQL dependencies without breaking release ### Phase B: Script-path migration -- Move workflow helper scripts out of `bsctl/scripts/workflows/`. +- Workflow helper scripts are now in `scripts/workflows/`; keep call sites aligned. - Update all workflow call sites to the new script locations. - Validate behavior parity in CI. diff --git a/resources/version.yaml b/resources/version.yaml index ac5b321f..3d67996d 100644 --- a/resources/version.yaml +++ b/resources/version.yaml @@ -1,2 +1,2 @@ # BasicSetupCliVersion - primary version source for releases and docs bump automation -BasicSetupCliVersion: "0.1.21" +BasicSetupCliVersion: "0.1.22" diff --git a/bsctl/scripts/workflows/action-validator_check-actions_lint-actions.sh b/scripts/workflows/action-validator_check-actions_lint-actions.sh similarity index 50% rename from bsctl/scripts/workflows/action-validator_check-actions_lint-actions.sh rename to scripts/workflows/action-validator_check-actions_lint-actions.sh index aa22bea8..102f1f46 100755 --- a/bsctl/scripts/workflows/action-validator_check-actions_lint-actions.sh +++ b/scripts/workflows/action-validator_check-actions_lint-actions.sh @@ -1,5 +1,5 @@ #! /usr/bin/env bash -find .github/workflows -type f \( -iname \*.yaml -o -iname \*.yml \) \ - | grep -v codeql.yaml \ - | xargs -I {} action-validator --verbose {} +find .github/workflows -type f \( -iname \*.yaml -o -iname \*.yml \) | + grep -v codeql.yaml | + xargs -I {} action-validator --verbose {} diff --git a/bsctl/scripts/workflows/agents-validate_agents-instructions-check.sh b/scripts/workflows/agents-validate_agents-instructions-check.sh similarity index 100% rename from bsctl/scripts/workflows/agents-validate_agents-instructions-check.sh rename to scripts/workflows/agents-validate_agents-instructions-check.sh diff --git a/bsctl/scripts/workflows/dependabot-autobump_bump-version.sh b/scripts/workflows/dependabot-autobump_bump-version.sh similarity index 100% rename from bsctl/scripts/workflows/dependabot-autobump_bump-version.sh rename to scripts/workflows/dependabot-autobump_bump-version.sh diff --git a/bsctl/scripts/workflows/dependabot-autobump_update-changelog.sh b/scripts/workflows/dependabot-autobump_update-changelog.sh similarity index 100% rename from bsctl/scripts/workflows/dependabot-autobump_update-changelog.sh rename to scripts/workflows/dependabot-autobump_update-changelog.sh diff --git a/bsctl/scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh b/scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh similarity index 100% rename from bsctl/scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh rename to scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh diff --git a/bsctl/scripts/workflows/docs-bump_docs-bump_version-bump.sh b/scripts/workflows/docs-bump_docs-bump_version-bump.sh similarity index 100% rename from bsctl/scripts/workflows/docs-bump_docs-bump_version-bump.sh rename to scripts/workflows/docs-bump_docs-bump_version-bump.sh From 1302505af2e06d12f7f1f24afc27751a358e1f18 Mon Sep 17 00:00:00 2001 From: Andrew Shoell Date: Wed, 8 Apr 2026 21:51:27 -0600 Subject: [PATCH 2/4] fix: install yq in docs-bump workflow --- .github/workflows/docs-bump.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/docs-bump.yaml b/.github/workflows/docs-bump.yaml index e8e3c9b7..6746f819 100644 --- a/.github/workflows/docs-bump.yaml +++ b/.github/workflows/docs-bump.yaml @@ -18,6 +18,9 @@ jobs: - name: Checkout repository uses: actions/checkout@v6 + - name: Install yq + uses: mikefarah/yq@v4 + - name: Version Bump run: ./scripts/workflows/docs-bump_docs-bump_version-bump.sh From fead33faba982ee14424202f9cea161dda260e1f Mon Sep 17 00:00:00 2001 From: Andrew Shoell Date: Wed, 8 Apr 2026 21:57:28 -0600 Subject: [PATCH 3/4] docs: define post-codeql static checks for #320 phase C --- CHANGELOG.md | 1 + docs/plans/bsctl-codeql-decommission-plan.md | 15 ++++++++++----- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c32df459..2b2e5f41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Migrated workflow helper scripts from `bsctl/scripts/workflows/` to `scripts/workflows/` and updated workflow call sites (`docs-bump`, `dependabot-autobump`, `action-validator`, and `agents-validate`). - Updated #320 decommission planning docs to reflect completed script-path migration and the new neutral script location. +- Expanded #320 Phase C planning to replace Go-focused CodeQL with shell/workflow static checks (`shellcheck`, `shfmt -d`, and `actionlint` alongside existing action-validator; optional targeted `semgrep`). --- ## [0.1.21] - 2026-04-09 diff --git a/docs/plans/bsctl-codeql-decommission-plan.md b/docs/plans/bsctl-codeql-decommission-plan.md index b8ac8f8c..f558f853 100644 --- a/docs/plans/bsctl-codeql-decommission-plan.md +++ b/docs/plans/bsctl-codeql-decommission-plan.md @@ -17,7 +17,7 @@ Retire remaining `bsctl` Go CLI and CodeQL dependencies without breaking release | Docs bump workflow | `.github/workflows/docs-bump.yaml` invokes `scripts/workflows/docs-bump_*` | Enforces version/changelog divergence and date checks | Keep scripts in root-level workflow script location | Docs-bump checks pass using replacement scripts | | Dependabot autobump | `.github/workflows/dependabot-autobump.yaml` invokes `scripts/workflows/dependabot-autobump_*` and stages `resources/version.yaml` (plus legacy constants during transition) | Automates patch bump + changelog update for dep PRs | Keep script paths and finalize legacy-version cleanup later | Dependabot autobump PR succeeds without `bsctl` references | | Action validator and agents validate | Workflows call scripts in `scripts/workflows/*` | Existing script organization | Keep scripts in neutral location | Validation workflows remain green after path migration | -| Code scanning | `.github/workflows/codeql.yaml` scans Go | Security coverage for Go code under `bsctl/` | Re-scope/remove CodeQL after supported-language coverage decision | `bsctl` removal complete and security coverage documented | +| Code scanning | `.github/workflows/codeql.yaml` scans Go | Security coverage for Go code under `bsctl/` | Replace Go-focused CodeQL with shell-focused/static checks (`shellcheck`, `shfmt -d`, `actionlint`/`action-validator`, optional targeted `semgrep`) before removing CodeQL | CodeQL retirement approved and replacement checks are green in CI | | Label automation | `.github/labeler.yaml` maps `bsctl/**/*` to change labels | Surfacing path-based impact in PRs | Replace with new paths or retire mapping if no longer needed | Label behavior remains correct after path removals | | Agent guidance and skills | `AGENTS.md`, `.agents/skills/*.md`, docs reference `resources/version.yaml` (legacy mention only for transition) | Instructions aligned with current version source | Update docs to new source-of-truth path | No remaining mandatory guidance references to retired path | @@ -38,7 +38,12 @@ Retire remaining `bsctl` Go CLI and CodeQL dependencies without breaking release ### Phase C: CodeQL decision and transition - Confirm post-Go supported language set and required scanning coverage. -- Re-scope or remove `.github/workflows/codeql.yaml` accordingly. +- Introduce replacement static checks for current repo surface: + - `shellcheck` for shell script correctness and safety. + - `shfmt -d` for shell formatting enforcement. + - `actionlint` (alongside existing `action-validator`) for workflow validation. + - Optional: targeted `semgrep` rules for shell/workflow security patterns if signal-to-noise is acceptable. +- Re-scope or remove `.github/workflows/codeql.yaml` only after replacement checks are enforced in CI. - Document rationale and replacement security posture. ### Phase D: `bsctl/` retirement @@ -56,6 +61,6 @@ Retire remaining `bsctl` Go CLI and CodeQL dependencies without breaking release ## Immediate Next Steps -1. Confirm the replacement version source file and ownership. -2. Draft implementation PR for Phase A (smallest possible change set). -3. Queue Phase B path migration after Phase A lands. +1. Complete Phase B PR merge and verify workflow parity on `main`. +2. Start Phase C by adding shell/workflow static checks (`shellcheck`, `shfmt -d`, `actionlint`) in CI. +3. Reassess CodeQL scope and retire/re-scope `.github/workflows/codeql.yaml` once replacement checks are stable. From 595ff5f83f289345c27879ead16d07bb30db89ea Mon Sep 17 00:00:00 2001 From: Andrew Shoell Date: Wed, 8 Apr 2026 21:59:53 -0600 Subject: [PATCH 4/4] docs: updating agent behavior --- AGENTS.md | 7 +++++++ CHANGELOG.md | 1 + 2 files changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5cba5ba5..dba0ebfd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,9 +52,15 @@ Use `.agents/work-snapshot.local.md` as a local handoff aid, not as source-of-tr When implementing work tied to an issue/PR, proactively detect scope creep and preserve reviewable units. +### Git action guardrail + +- Never create commits or push branch updates unless the user explicitly asks for a commit/push in the current session. +- Staging and local validation are allowed as preparation, but commit/push is opt-in only. + 1. **Detect scope creep early** - Treat newly identified, non-blocking improvements as potential follow-up scope, not automatic additions. - Examples: adjacent hardening, separate automation, or unrelated workflow polish. + - Use an aggressive default: if a discovered change is not required for current acceptance criteria or to fix a blocking defect, classify it as out-of-scope. 2. **Pause and classify discovered work** - If work is required to complete the current acceptance criteria or fix a blocking defect, keep it in scope. @@ -63,6 +69,7 @@ When implementing work tied to an issue/PR, proactively detect scope creep and p 3. **Ask before expanding scope** - Present out-of-scope work to the user and ask whether to expand current scope or defer. - Default recommendation: keep the current PR focused and defer non-blocking work. + - If the user explicitly approves scope expansion, treat that approval as authoritative and proceed with the accepted expansion. 4. **If deferring, open a follow-up issue** - Create a new issue with clear summary, rationale, and acceptance criteria. diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b2e5f41..ff02ac83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Migrated workflow helper scripts from `bsctl/scripts/workflows/` to `scripts/workflows/` and updated workflow call sites (`docs-bump`, `dependabot-autobump`, `action-validator`, and `agents-validate`). - Updated #320 decommission planning docs to reflect completed script-path migration and the new neutral script location. - Expanded #320 Phase C planning to replace Go-focused CodeQL with shell/workflow static checks (`shellcheck`, `shfmt -d`, and `actionlint` alongside existing action-validator; optional targeted `semgrep`). +- Updated `AGENTS.md` scope-control guardrails to require explicit user request before commit/push and to apply a more aggressive default for classifying non-blocking discoveries as out-of-scope unless explicitly approved. --- ## [0.1.21] - 2026-04-09