feat(instructions): update Python and Terraform guidelines

.github/CHANGELOG.md

@@ -6,6 +6,10 @@ Use this format for new updates:
 - One bullet per meaningful change.
 - Include file/path scope when useful.
 
+## 2026-03-19
+- Updated `.github/copilot-instructions.md`, `.github/instructions/python.instructions.md`, and `.github/prompts/tech-ai-python.prompt.md` so Python tasks now standardize on human-readable hash-locked `requirements.txt` files for external dependencies, clarify that the lock file should capture the full dependency closure, and treat third-party libraries as a recommendation only when they materially simplify the code.
+- Updated `.github/prompts/tech-ai-python-script.prompt.md`, `.github/skills/tech-ai-script-python/SKILL.md`, and `.github/instructions/bash.instructions.md` so new standalone Python tools default to a self-contained folder with a `run.sh` launcher, add a local `requirements.txt` only when external packages are used, and bootstrap `.venv` plus locked dependency installation only when that file exists.
+
 ## 2026-03-13
 - Updated `.pre-commit-config.yaml` to pin `pre-commit-hooks` `v6.0.0`, keep `pre-commit-terraform` explicitly annotated at `v1.105.0`, and move `shellcheck-py` to `v0.11.0.1`, adding inline release comments for each pinned revision.
 - Updated `.github/workflows/github-validate-copilot-customizations.yml` to pin the runner to `ubuntu-24.04`, add `actions/setup-python` pinned by SHA for Python `3.14.3`, pin `pip` to `26.0.1`, and replace the unpinned `apt` shellcheck install with the pinned Python dependency set from `.github/tech-ai-requirements-dev.txt`.

.github/README.md

@@ -12,7 +12,7 @@ This folder is the **single source of truth** for GitHub Copilot customization a
 | --- | --- | --- | --- |
 | `copilot-instructions.md` | Global non-negotiable rules: language policy, least privilege, DDD preference, test execution order, script standards, validation baseline. | Every Copilot interaction — this is the root of the instruction chain. | Never skip — it's always loaded first. |
 | `copilot-commit-message-instructions.md` | Commit message format: `<type>(<scope>): <summary>`, imperative mood, 72-char limit. | Writing commits via Copilot or reviewing commit messages. | Manual commits that follow the same convention already. |
-| `copilot-code-review-instructions.md` | Review severity levels, baseline checks, escalation rules. References `tech-ai-code-review/SKILL.md` for anti-pattern catalogs. | Running Copilot code review or configuring review agents. | Deep per-line review (use `TechAIScriptReviewer` instead). |
+| `copilot-code-review-instructions.md` | Review severity levels, baseline checks, escalation rules. References `tech-ai-code-review/SKILL.md` for anti-pattern catalogs. | Running Copilot code review or configuring review agents. | General implementation guidance (see reviewer agents for specialized reviews). |
 | `security-baseline.md` | Portable security checklist: SHA-pinned actions, minimal permissions, OIDC, branch protection, prompt/agent safety. | Every infrastructure or workflow change. Referenced by all agents as a minimum bar. | Application-only code changes with no infra impact. |
 
 ### Configuration and governance
@@ -109,7 +109,7 @@ Implementation knowledge bases loaded on demand by agents and prompts. They cont
 | --- | --- | --- |
 | `tech-ai-pair-architect` | DDD analysis dimensions, severity mappings, health score, risk matrix format, report template for change-impact analysis. | Agent `TechAIPairArchitect`, prompt `tech-ai-pair-architect-analysis` |
 | `tech-ai-pair-architect-analysis-executor` | Decision-table format, execution plan template, disagreement protocol, quality checklist for re-evaluating analysis reports. | Agent `TechAIPairArchitectAnalysisExecutor` |
-| `tech-ai-code-review` | Per-language anti-pattern catalogs (Python, Bash, Terraform), severity mappings, escalation rules for exhaustive code review. | Agents `TechAIScriptReviewer`, `TechAIPairArchitect`; prompt `tech-ai-code-review` |
+| `tech-ai-code-review` | Per-language anti-pattern catalogs (Python, Bash, Terraform), severity mappings, escalation rules for exhaustive code review. | Agents `TechAIBashReviewer`, `TechAIPythonReviewer`, `TechAITerraformReviewer`, `TechAIPairArchitect`; prompt `tech-ai-code-review` |
 | `tech-ai-pr-editor` | PR description templates, section structure, and diff-to-description mapping for generating review-ready PR bodies. | Agent `TechAIPREditor`, prompt `tech-ai-pr-description` |
 | `tech-ai-project-java` | Java component scaffolding: purpose JavaDoc, BDD-like JUnit 5 tests, module conventions. | Prompt `tech-ai-java` |
 | `tech-ai-project-nodejs` | Node.js module scaffolding: purpose comments, `node:test` tests, adapter patterns. | Prompt `tech-ai-nodejs` |
@@ -149,10 +149,9 @@ Three complementary levels of review — they do NOT overlap.
 | Agent | Purpose | Scope | Example trigger | When to use instead of the others |
 | --- | --- | --- | --- | --- |
 | `TechAIReviewer` | Structured code review: defects, regressions, maintainability. Diff-first, broad. | Any language, any change | "Review this PR for quality before merge." | **Default choice** for general PR review. Delegates to specialists when needed. |
-| `TechAIScriptReviewer` | Exhaustive nit-level review with per-language anti-pattern catalogs + architecture assessment. | Python, Bash, Terraform only | "Deep review of the new sync script — catch every anti-pattern." | When you want **every possible finding** on scripts/infra code, including Nits and architecture verdict. |
 | `TechAISecurityReviewer` | Security-focused review: secrets, permissions, attack surface, compliance. | Any change with security impact | "Security review of the new IAM module and workflow changes." | When the change touches **security-sensitive** code (IAM, secrets, auth, networking). |
 
-> **How they differ**: `TechAIReviewer` is the broad quality gate (like a senior engineer's PR review). `TechAIScriptReviewer` is the exhaustive deep-dive (like a specialized linter on steroids — only for Python/Bash/Terraform). `TechAISecurityReviewer` focuses exclusively on security concerns. Use `TechAIReviewer` first; it will recommend routing to a specialist when needed.
+> **How they differ**: `TechAIReviewer` is the broad quality gate (like a senior engineer's PR review). `TechAISecurityReviewer` focuses exclusively on security concerns. Use `TechAIReviewer` first; it will recommend routing to a specialist when needed.
 
 #### Infrastructure specialist agents
 
@@ -183,7 +182,6 @@ These agents manage the **lifecycle** of Copilot customization assets. They are
 | Potential confusion | Verdict | Distinction |
 | --- | --- | --- |
 | `TechAIPairArchitect` vs `TechAIReviewer` | **Different scope** | PairArchitect does cross-cutting architecture/DDD analysis of the full change set. Reviewer does per-file defect-focused PR review. Use PairArchitect for design-level assessment, Reviewer for merge readiness. |
-| `TechAIReviewer` vs `TechAIScriptReviewer` | **Different depth** | Reviewer is broad and delegates to specialists. ScriptReviewer is exhaustive nit-level for Python/Bash/Terraform only. Use Reviewer first; use ScriptReviewer when you want zero findings missed. |
 | `TechAIPlanner` vs `TechAIPairArchitectAnalysisExecutor` | **Different input** | Planner works from requirements/user intent. Executor works from an existing `ANALYSIS_REPORT.md`. Planner is upstream (before code); Executor is downstream (after analysis). |
 
 ### Scripts (`scripts/`)
@@ -225,7 +223,7 @@ These agents manage the **lifecycle** of Copilot customization assets. They are
 
 - `repo-profiles.yml` is advisory-only (human-readable profile catalog, not enforced by validators).
 - The canonical project `AGENTS.md` belongs at repository root, not under `.github/`.
-- **Repo-only agents** (not synced to consumers): `TechAISyncGlobalCopilotConfigsIntoRepo`, `TechAIScriptReviewer`.
+- **Repo-only agents** (not synced to consumers): `TechAISyncGlobalCopilotConfigsIntoRepo`.
 - **Source-only assets** (excluded from consumer baselines): `.github/README.md`, `agents/README.md`, `templates/**`, `scripts/bootstrap-copilot-config.sh`, `tech-ai-requirements-dev.txt`, `.bootstrap-ignore`.
 - Use `templates/copilot-quickstart.md` for onboarding new consumer repos.
 

.github/agents/README.md

@@ -15,7 +15,6 @@ This folder contains optional custom agents for focused tasks.
 - Write-capable: `TechAIImplementer`.
 
 ## Repo-only agents (not synced to consumers)
-- `TechAIScriptReviewer`
 - `TechAISyncGlobalCopilotConfigsIntoRepo`
 
 ## Why generic core agents

.github/copilot-instructions.md

@@ -64,6 +64,9 @@ These apply to every code change, regardless of language or technology:
 - Use simple control flow and early returns.
 - Bash: always `#!/usr/bin/env bash` (never POSIX `sh`).
 - Python: add unit tests for testable logic.
+- Python dependencies: when external packages are introduced, standardize on a compiled `requirements.txt` with exact pins, full transitive dependency closure, and `--hash` entries, plus short comment lines that make the pinned versions readable to humans.
+- Python dependencies: third-party libraries are recommended when they materially simplify parsing, validation, HTTP, CLI, serialization, or retry logic; keep the standard library when it is simpler and safer.
+- New standalone Python scripts should default to a self-contained folder that includes the Python entry point, a Bash launcher, and a local `requirements.txt` only when external packages are required. The launcher should bootstrap `.venv` and install from `requirements.txt` only when that file exists.
 - Prefer immutable dependency and image pins; keep stack-specific locking details in the matching instruction file.
 
 ## Java and Node.js standards

.github/instructions/bash.instructions.md

@@ -35,6 +35,7 @@ set -euo pipefail
 - Use `getopts` for argument parsing.
 - Keep logic simple and avoid unnecessary complexity.
 - Validate inputs and handle errors gracefully.
+- When the Bash script is a launcher for a standalone Python tool, resolve its own directory, create or reuse a sibling `.venv`, install from the local hash-locked `requirements.txt` if it exists, and execute the sibling Python entry point.
 
 ## Validation
 - `bash -n <script>.sh`

.github/instructions/python.instructions.md

@@ -9,8 +9,8 @@ applyTo: "**/*.py"
 - Use emoji logs for key execution states.
 - Prefer early return and clear guard clauses.
 - Keep code explicit and readable.
-- Prefer well-maintained libraries (stdlib first, then approved third-party) when they simplify code and reduce custom logic.
-- Do not reinvent common parsing/validation/serialization behavior when a library provides a clear solution.
+- Prefer the standard library first. Introduce well-maintained third-party libraries when they materially simplify code and reduce custom logic.
+- Do not reinvent common parsing/validation/serialization behavior when the standard library or a well-maintained library provides a clearer solution.
 - Prefer simple, readable, and easily modifiable code over clever abstractions.
 - Accept additional lines or mild redundancy when it improves clarity, maintainability, and safe future changes.
 - Unit tests are required for testable logic.
@@ -37,8 +37,22 @@ applyTo: "**/*.py"
 - Docstrings, logs, exceptions, and CLI output must be in English.
 
 ## Dependencies
-- If external libraries are needed, prefer a compiled `requirements.txt` with hashes.
-- When hash-locked requirements are not feasible, use exact `==` pins and document the reason in the closest technical note or workflow comment.
+- Standardize on `requirements.txt` as the Python dependency lock artifact in this baseline.
+- If external libraries are introduced, prefer a compiled `requirements.txt` with exact `==` pins, full transitive dependency closure, and `--hash` entries for every locked requirement.
+- Keep a short comment above each introduced dependency block so the pinned version is readable without parsing the full hash line.
+- Recommend third-party libraries when they materially reduce custom parsing, validation, HTTP, CLI, serialization, or retry code.
+- Do not force third-party libraries over the standard library when the standard library is simpler, clearer, or safer.
+- When a fully hash-locked `requirements.txt` is not feasible, use exact `==` pins in `requirements.txt` and document the reason in the closest technical note or workflow comment.
+
+## Dependency example
+```text
+# requests 2.32.3
+requests==2.32.3 \
+    --hash=sha256:<hash1> \
+    --hash=sha256:<hash2>
+```
+
+- Generate the locked file with `pip-compile --generate-hashes` or an equivalent workflow that captures the full dependency closure.
 
 ## Testing defaults
 - Use `pytest` as default unit-test framework.

.github/instructions/terraform.instructions.md

@@ -13,7 +13,13 @@ applyTo: "**/*.tf"
 ## Naming conventions
 - Resources: `snake_case` (for example `aws_iam_role.lambda_execution`).
 - Variables: `snake_case` with `description`.
-- Locals: `snake_case`, grouped by domain.
+- Locals: `snake_case`, grouped by domain. Avoid using locals for hardcoded variables.
+
+## Variables and Values (Non-Module code)
+- Avoid using `default` values in variables as much as possible (except for Terraform modules).
+- Configuration values must be defined in `.tfvars` files.
+- For resources configurations, use direct hardcoded values in the code unless they change per environment (and thus require a variable).
+- These rules do not apply to reusable standalone modules.
 
 ## Structure
 - Always add `description` to variables.

.github/prompts/tech-ai-python-script.prompt.md

@@ -8,7 +8,7 @@ argument-hint: action=<create|modify> script_name=<name> purpose=<purpose> [targ
 # TechAI Python Script
 
 ## Context
-Create or modify a Python script while keeping interfaces explicit, behavior deterministic, and tests focused.
+Create or modify a standalone Python script while keeping interfaces explicit, behavior deterministic, and the delivery package self-contained.
 
 ## Required inputs
 - **Action**: ${input:action:create,modify}
@@ -25,14 +25,20 @@ Create or modify a Python script while keeping interfaces explicit, behavior det
 4. If `action=modify` and tests already exist, run the existing tests before editing them.
 5. Add or update deterministic tests only for intentional behavior changes or uncovered new behavior when `test_scope=unit`.
 6. Use Jinja templates named `<file-name>.<extension>.j2` when the task includes Python-managed templates.
-7. Follow `.github/instructions/python.instructions.md` for dependency locking.
+7. For new standalone scripts, prefer a dedicated folder at `<target_path>/<script_name>/` instead of a loose single `.py` file.
+8. The standalone script folder should contain the Python entry point and a `run.sh` launcher. Add a local `requirements.txt` only when external packages are used.
+9. When external packages are used, standardize on `requirements.txt` with exact pins, full transitive dependency closure, hashes, and short comment lines that keep pinned versions readable.
+10. External libraries are recommended when they materially simplify the script, but they are not mandatory if the standard library is simpler.
+11. Follow `.github/instructions/python.instructions.md` for dependency locking.
+12. Make new `run.sh` launchers executable, and ensure they bootstrap or reuse `.venv`, install from the local `requirements.txt` when present, and invoke the Python entry point.
 
 ## Minimal example
 - Input: `action=modify script_name=inventory_report purpose="Summarize customization assets" target_file=.github/scripts/inventory_report.py test_scope=unit`
 - Expected output:
-  - Updated Python script with explicit CLI behavior and focused deterministic tests.
+  - Updated standalone Python script package with explicit CLI behavior, a Bash launcher, optional local dependency lock data when external packages are required, and focused deterministic tests.
 
 ## Validation
 - Run `python -m compileall <changed_python_paths>`.
 - Run `pytest` for the changed script/tests when present.
+- Run `bash -n` on generated or modified launcher scripts.
 - Run `bash .github/scripts/validate-copilot-customizations.sh --scope root --mode strict` when changing Copilot assets.

.github/prompts/tech-ai-python.prompt.md

@@ -30,7 +30,8 @@ Create or modify Python application components with clear separation of concerns
 7. If the task includes Python templates, use Jinja templates named `<file-name>.<extension>.j2`.
 8. If `action=modify` and tests already exist, run existing tests before editing test files.
 9. Add or update deterministic `pytest` unit tests only after the first test run, and only for intentional behavior changes or uncovered new behavior.
-10. Follow `.github/instructions/python.instructions.md` for dependency locking.
+10. Follow `.github/instructions/python.instructions.md` for dependency locking, `requirements.txt` standardization, and external-library selection.
+11. If external packages are introduced, create or update `requirements.txt` so it uses exact pins, full transitive dependency closure, hashes, and short human-readable version comments.
 
 ## Minimal example
 - Input: `action=create component_type=service component_name=PolicyEvaluator purpose="Evaluate policy eligibility"`