Fix Guardrails

Fix all guardrail findings (make lint, make test, make sast) across one or more repositories. This is a complete, repeatable workflow: sync with main, run all guardrails, fix every finding, update documentation, commit following standards, push, and create PRs.

For guardrail tools, refer to the CI/CD rule and Security rule. For commit conventions, refer to the Git Flow rule. For changelog updates, refer to the Documentation rule.

Vendor Detection

Auto-detect the Git hosting vendor from git remote get-url origin to determine the correct PR creation CLI:

Step-by-step Workflow (repeat for every repository)

Step 1 -- Sync with the default branch

cd <REPO_PATH>
git checkout <default-branch>
git fetch --all
git pull --rebase

• Detect the default branch with git symbolic-ref refs/remotes/origin/HEAD (strip refs/remotes/origin/). Fall back to main if unavailable.
• If pull --rebase fails due to conflicts, report the failure and skip this repo.

Step 2 -- Run all three guardrails

Run them in this exact order. Each gate must be evaluated independently -- even if one passes, the others may fail.

Gate 1: Lint

make lint

• Timeout: 3 minutes.
• Parse the output. Record every finding with file path, line number, rule, and message.
• NEVER invoke linter binaries directly. Always use make lint.

Gate 2: Test

make test

• Timeout: 5 minutes.
• Record any failing test names and error messages.
• NEVER invoke test runners directly. Always use make test.

Gate 3: SAST

make sast

• Timeout: 10 minutes -- SAST is the slowest gate (it runs CodeQL, Semgrep, Trivy, Hadolint, and Gitleaks).
• Parse the output. Record every finding with tool name, rule ID, file path, line number, and description.
• NEVER invoke SAST tools directly. Always use make sast.

Decision point

• If all three gates pass with 0 findings: print <repo>: SKIP(clean) and move to the next repo.
• If any gate has findings: proceed to Step 3.

Step 3 -- Create the feature branch

git checkout -b fix/<scope>

Branch naming rules (from the Git Flow rule):

• Format: type/scope
• Choose the scope based on what was found:
  • Lint-only findings: fix/lint-findings
  • SAST-only findings: fix/sast-findings
  • Test-only findings: fix/test-findings
  • Mixed findings: fix/guardrail-findings
  • If a specific tool dominates: fix/codeql-findings, fix/semgrep-findings, etc.
• The branch type is always fix for guardrail remediation.

Step 4 -- Fix each finding

Read the affected files, understand the context, and apply a minimal, targeted fix for each finding. Never refactor surrounding code.

4a. Lint fix patterns

4b. Test fix patterns

Important: Tests must follow BDD structure (// given, // when, // then). If you modify a test, preserve or add this structure.

4c. SAST fix patterns

CodeQL:

Semgrep:

Trivy (IaC scanning):

Hadolint (Dockerfile):

Gitleaks (secrets):

For any rule not listed above: analyze the code, apply a minimal fix, and document the new pattern in the commit message body.

Step 5 -- Verify build

Run the appropriate build verification for the detected language:

If compilation fails, diagnose and fix before proceeding.

Step 6 -- Re-run the failing guardrails

After applying fixes, re-run only the guardrails that originally failed:

make lint   # if lint had findings
make test   # if tests were failing
make sast   # if SAST had findings

If new findings appear, fix them. Repeat until all three gates pass. If you cannot resolve a finding after 2 attempts, document it and proceed -- the PR description should note unresolved items.

Step 7 -- Update CHANGELOG.md

Read the existing CHANGELOG.md. Under ## [Unreleased], add entries in the appropriate category. Follow the Documentation rule for changelog conventions:

• Use simple past tense: "fixed", "removed", "replaced"
• Start each entry with a lowercase verb
• Use Keep a Changelog categories

Step 8 -- Stage and commit

Stage only the files you changed. Follow the Git Flow rule for commit message format:

• Format: fix(<scope>): <subject in simple past tense>
• Use bullet points for multi-file changes

Step 9 -- Push the branch

GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=15" git push -u origin <branch> --force

• --force is safe because this is a new branch we just created

Step 10 -- Restore the original branch

git checkout <default-branch>

Step 11 -- Create Pull Request

Use the detected vendor CLI (GitHub: gh pr create, Azure DevOps: az repos pr create, GitLab: glab mr create).

PR title rules:

• Format: fix(<scope>): resolved <tool/gate> findings
• Under 70 characters
• Simple past tense, lowercase

Error Handling