chore(dx): add nan baseline checks and contribution evidence workflow

Author: matiasz8

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,29 +1,43 @@
-## Description
+## Summary
 
-Please include a summary of the changes and the related issue. List any dependencies that are required for this change.
+Describe what changed and why.
 
-Fixes # (issue)
+Issue: Fixes #
 
-## Type of Change
+## Change Type
 
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
 - [ ] Documentation update
+- [ ] Dependency update
 
-## How Has This Been Tested?
+## Validation Evidence
 
-Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.
+List the exact commands executed and a short result summary.
 
-- [ ] Test A
-- [ ] Test B
+```bash
+make lint
+make type-check
+make test-unit
+```
+
+Optional baseline checks (if available):
+
+```bash
+make check-env
+make nan-health
+```
+
+## Risk and Rollback
+
+- Risk level: [Low | Medium | High]
+- Rollback plan:
 
 ## Checklist
 
-- [ ] My code follows the style guidelines of this project
-- [ ] I have performed a self-review of my code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] Any dependent changes have been merged and published in downstream modules
-- [ ] I have checked my code and corrected any misspellings
+- [ ] Scope is focused and minimal
+- [ ] Tests and/or checks relevant to this change were executed
+- [ ] Docs were updated when behavior changed
+- [ ] No secrets or sensitive data were added
+- [ ] I verified spelling and basic formatting

AGENTS.md

@@ -1,12 +1,29 @@
 # AI Agents Guidelines
 
+## Instruction Priority
+
+When instructions conflict, follow this order:
+
+1. `AGENTS.md` (this file)
+2. `CONTRIBUTING.md`
+3. `README.md` and `docs/`
+
+Escalate to a human when guidance is ambiguous or potentially destructive.
+
 ## Principles
 
 - Keep implementations generic and reusable.
 - Avoid source/vendor-specific hardcoding in shared modules.
 - Prefer configuration via environment variables or Glue job arguments.
 - Follow Medallion separation (`raw`, `bronze`, `silver`, `gold`).
 
+## Automation Boundaries
+
+- Prefer minimal and reversible edits.
+- Do not run destructive operations on cloud resources without explicit confirmation.
+- Do not modify deployment/release workflows beyond the task scope.
+- Keep boilerplate defaults vendor-neutral unless the change explicitly targets this repo.
+
 ## Security
 
 - Never hardcode credentials or tokens.
@@ -16,3 +33,14 @@
 
 - Keep changes minimal and focused.
 - Update tests/docs when behavior changes.
+- Include explicit validation evidence for the commands executed.
+
+## NaNLABS Baseline (Recommended)
+
+If available in the environment, use:
+
+- `nan-doctor` to validate workstation health
+- `nan-skills list` to discover available skills and helpers
+- `nan-update-check` to verify baseline/tool updates
+
+These commands are recommended but optional for external contributors.

CONTRIBUTING.md

@@ -7,6 +7,22 @@
 3. Run tests and checks.
 4. Open a pull request with clear scope and validation notes.
 
+## NaNLABS Local Baseline (Recommended)
+
+When available in your workstation, run these checks before opening a PR:
+
+```bash
+nan-doctor
+nan-skills list
+nan-update-check
+```
+
+If `nan-*` commands are not installed, continue with the project checks (`make lint`, `make type-check`, tests).
+
+## Validation Evidence
+
+In each PR, include the commands you executed and a short result summary (pass/fail + key notes).
+
 ## Conventions
 
 - Keep shared code source-agnostic.

Makefile

@@ -12,7 +12,7 @@
 #
 # All commands below are designed to run INSIDE the dev container environment.
 
-.PHONY: help bootstrap install install-dev requirements clean test test-unit test-integration test-coverage lint type-check format autofix validate migrate migrate-upload migrate-dry-run services-status spark-submit pyshell-run notebook prepare-localstack clean-localstack aws-login scaffold-source run-raw run-bronze run-silver run-gold
+.PHONY: help bootstrap install install-dev requirements clean test test-unit test-integration test-coverage lint type-check format autofix validate check-env nan-health nan-skills migrate migrate-upload migrate-dry-run services-status spark-submit pyshell-run notebook prepare-localstack clean-localstack aws-login scaffold-source run-raw run-bronze run-silver run-gold
 
 # Default target
 help:
@@ -31,6 +31,9 @@ help:
 	@echo "  install-dev     - Install development dependencies"
 	@echo "  requirements    - Generate requirements.txt from Pipfile"
 	@echo "  validate        - Validate dev container environment"
+	@echo "  check-env       - Validate environment + optional nan-doctor"
+	@echo "  nan-health      - Run optional NaNLABS baseline checks"
+	@echo "  nan-skills      - List available NaNLABS skills (if installed)"
 	@echo ""
 	@echo "🧪 Testing & Quality:"
 	@echo "  test            - Run all tests (unit + integration)"
@@ -163,6 +166,38 @@ validate:
 	@echo "🔍 Validating dev container environment..."
 	./scripts/validate-env.sh
 
+# Validate project environment plus optional NaNLABS checks
+check-env: validate
+	@echo ""
+	@echo "🔎 Optional NaNLABS environment check..."
+	@if command -v nan-doctor >/dev/null 2>&1; then \
+		nan-doctor; \
+	else \
+		echo "ℹ️ nan-doctor not found; skipping optional baseline check."; \
+	fi
+
+# Run optional NaNLABS workstation checks without blocking contributors
+nan-health:
+	@echo "🩺 Running optional NaNLABS checks..."
+	@if command -v nan-doctor >/dev/null 2>&1; then \
+		nan-doctor; \
+	else \
+		echo "ℹ️ nan-doctor not found; skipping."; \
+	fi
+	@if command -v nan-update-check >/dev/null 2>&1; then \
+		nan-update-check; \
+	else \
+		echo "ℹ️ nan-update-check not found; skipping."; \
+	fi
+
+# List available NaNLABS skills when baseline is installed
+nan-skills:
+	@if command -v nan-skills >/dev/null 2>&1; then \
+		nan-skills list; \
+	else \
+		echo "ℹ️ nan-skills not found; skipping."; \
+	fi
+
 # Check status of all services
 services-status:
 	@echo "🔧 Checking dev container services status..."

README.md

@@ -92,6 +92,14 @@ This sets up `uv`, creates `.venv`, installs runtime/dev dependencies, and runs
 
 Optional manual setup is still available via `uv` if you need a custom environment.
 
+Optional NaNLABS baseline checks (if installed):
+
+```bash
+make check-env
+make nan-health
+make nan-skills
+```
+
 ### 2. Set up environment variables
 
 ```bash
@@ -165,6 +173,10 @@ make test-integration
 # Quality checks
 make lint
 make type-check
+
+# Optional baseline checks
+make check-env
+make nan-health
 ```
 
 See [docs/TESTING.md](docs/TESTING.md) for conventions and marker usage.

docs/DEVELOPMENT.md

@@ -1,5 +1,22 @@
 # Development Guide
 
+## Recommended local flow
+
+```bash
+make bootstrap
+make check-env
+make lint
+make type-check
+make test-unit
+```
+
+Optional NaNLABS commands (if available):
+
+```bash
+make nan-health
+make nan-skills
+```
+
 ## Local run examples
 
 ```bash

docs/TESTING.md

@@ -1,5 +1,22 @@
 # Testing
 
+## Validation matrix
+
+Required project checks:
+
+```bash
+make lint
+make type-check
+make test-unit
+```
+
+Recommended NaNLABS baseline checks (optional):
+
+```bash
+make check-env
+make nan-health
+```
+
 ## Unit tests
 
 Run: