Status: draftCreated: 2026-06-30Last updated: 2026-07-05

Document Scope

This document governs runtime and operational validation for repository changes made inside the modular workspace. It is written for human operators, ChatGPT sessions, Codex sessions, AI-assisted development tools, future AI agents, automation workers, and future MCP or RAG systems that need to decide which checks are appropriate before a change is treated as safe.

This standard applies to the active repository named in a task. Validation expectations depend on repository class: deployable repositories, server/infrastructure repositories, context/reference repositories, and personal utility repositories require different validation depth. It is especially relevant when a change affects executable code, scripts, workers, API routes, service modules, database access, schema migrations, configuration templates, object storage behavior, stable report access, scheduler behavior, CI/CD pipeline behavior, monitoring tools, alerting, generated reports, public output quality, or operational records.

This document does not define the patch-helper workflow, Codex prompt format, Git commit-message standard, CI/CD pipeline standard, production deployment process, or provider-specific resource setup. Those topics are governed by separate workflow standards and runbooks. This document defines how to choose, run, and record validation after a change has been made and before the change is considered safe.

1. Purpose

The purpose of this document is to prevent edited files from being mistaken for safe files.

A change is not safe merely because it was applied successfully, because an AI tool said it completed the task, or because a syntax check passed. Runtime validation must match the behavior affected by the change.

The project is moving toward a structured platform architecture with a Python project manager, standardized linting and formatting, automated tests, explicit models, centralized configuration, a standardized database access layer, an API layer, internal dashboards, terminal tools, object storage, email delivery, Telegram delivery, operations jobs, and future AI-agent workflows. Validation must therefore be selected by layer and risk, not by file extension alone.

The goal is controlled execution. A safe checkpoint should have a visible scope, a known validation plan, recorded validation output, known skipped checks, reviewed Architectural Impact Review where repository work is involved, including CI/CD pipeline impact, clean Git state, and an explanation of remaining risks.

2. Layer and Tool Definitions

The following table defines the selected implementation for each layer where validation rules may apply. The rest of this document uses generic layer terms unless the specific selected implementation matters.

Validation area	Current selected implementation or direction	Preferred documentation term
Python project execution	`uv` after adoption; existing local interpreter during transition	approved Python runner
Python linting and formatting	Ruff	linting and formatting layer
Python testing	pytest	testing layer
API framework	FastAPI	API layer
API contract	OpenAPI	API contract
Data models	Pydantic	model layer
Structured configuration	Pydantic Settings	configuration layer
Database access	SQLAlchemy Core	database access layer
Schema migrations	Alembic where compatible	schema migration layer
Dynamic frontend	React, Next.js, TypeScript	frontend application layer
Static frontend	HTML, CSS, JavaScript, Markdown-generated pages	static site layer
Internal browser dashboards	Streamlit	internal dashboard layer
Terminal output	Rich	terminal output layer
Interactive terminal apps	Textual where justified	terminal application layer
Customer authentication	Better Auth	customer authentication layer
Bot protection	Turnstile Managed mode	bot-protection layer
Current scheduler	current operating-system scheduler	scheduler layer
Future scheduler	undecided; evaluate later	scheduler layer
Email	internal email service wrapper	email service layer
Object storage	provider-neutral object storage wrapper	object storage layer
Telegram	Telegram integration wrapper and Telegram APIs	Telegram integration layer
Documentation	Markdown source files	documentation layer
Diagrams	Mermaid	diagram format
Remote repository validation	remote Git CI/CD pipeline service; GitLab CI/CD currently	CI/CD pipeline layer
Pipeline configuration	repository-specific pipeline configuration file; `.gitlab-ci.yml` currently	pipeline configuration
Lightweight monitoring	`monitoring/watchdog.py`	Watchdog
Heavy feed audit	`monitoring/feed_audit.ps1`	Deep Audit
Deployable repository validation	`app`, `site`, `admin`, and future deployable repositories	deployable repository validation
Server/infrastructure validation	`server` currently	server/infrastructure repository validation
Context/reference validation	`ctx-*` repositories	context/reference repository validation
Personal utility validation	`echo` and similar repositories	personal utility repository validation

Use current literal commands when the user needs to run a command on the current machine. Use durable layer terms in standards and architecture documents.

2.1 Repository Classification Controls Validation Depth

Runtime validation starts with repository classification. The same file extension does not imply the same risk in every repository. A Markdown change in a context/reference repository may require source-inventory validation and no-secret checks. A Markdown change in an admin repository may affect rendered internal documentation. A script change in the server repository may affect startup behavior, scheduled tasks, tunnels, or future infrastructure. A dependency change in a deployable repository may affect build, release, SBOM, and signing expectations.

Before selecting validation commands, identify whether the repository is Class A, Class B, Class C, Class D, Class E, Class F, Class G, or multi-class. Apply the strictest applicable validation controls when a repository has more than one class.

3. Core Validation Rule

Validation must follow affected behavior.

For a documentation-only change, validation may be limited to required markers, document-library structure, spelling-sensitive terms, git diff --check, and git status --short.

For executable code, validation must include at least syntax or import checks and should include targeted tests or runtime checks when behavior changed.

For database, storage, gateway, scheduler, alerting, Telegram, API, configuration, or production-adjacent changes, validation must prove more than file existence. It must show that the changed behavior works, or that the remaining risk is understood and recorded.

Validation should be targeted. Do not run broad monitoring, Deep Audit, Watchdog, production jobs, live delivery tests, database mutations, external publishing commands, or expensive runtime checks unless the task explicitly requires them or the user approves them.

4. Validation Selection Process

Start by identifying the layer affected by the change.

Ask:

1. Did this change affect documentation only?
2. Did it affect executable code?
3. Did it affect import paths or package structure?
4. Did it affect configuration loading?
5. Did it affect Pydantic models or service contracts?
6. Did it affect API routes, request models, response models, or OpenAPI output?
7. Did it affect database access, queries, transactions, or schema?
8. Did it affect object storage, report artifacts, or stable access links?
9. Did it affect Telegram intake, processing, or publishing?
10. Did it affect email, alerts, or notification delivery?
11. Did it affect a scheduler, worker, recurring job, Watchdog, Deep Audit, monitoring output, or operational baseline?
12. Did it affect production safety, environment selection, or secrets?
13. Did it affect public/customer-facing output quality?
14. What repository class is affected: deployable application, server/infrastructure, context/reference, personal utility, or other?
15. Did it affect CI/CD pipeline configuration, pipeline jobs, build commands, test commands, deployment behavior, protected variables, documentation structure, reference-library structure, repository automation, Docker, Kubernetes, deployment packaging, supply-chain records, external artifacts, SBOM generation, Cosign signing, or future infrastructure automation?
16. Did it introduce, remove, upgrade, downgrade, mirror, pin, sign, scan, or depend on an external artifact governed by the Supply Chain Security Standard?

Select validation based on the highest-risk affected layer, not the easiest command to run.

If a validation command can mutate production data, send messages to real users, post to public channels, enqueue jobs, alter scheduler definitions, or change provider resources, stop and obtain explicit approval before running it.

4.1 Supply Chain Validation

When a change affects external artifacts, validation must include supply-chain evidence appropriate to the artifact. This does not mean every dependency change requires a full production release. It means the validation record must prove that supply-chain impact was understood.

Supply-chain validation may include:

confirmed operator approval for the artifact decision status,
confirmed dependency file and lockfile changes are expected,
confirmed package source and version are recorded,
confirmed container image digest is recorded where applicable,
confirmed SBOM generation succeeds where applicable,
confirmed Cosign signing or verification succeeds where applicable,
confirmed CI/CD runner image or pipeline component is approved,
confirmed Technology Decision Record, Supply Chain Record, or Integration Record was updated where required,
confirmed no unapproved artifact entered the repository.

A syntax check cannot validate a supply-chain change by itself. If an artifact changed, the repository needs evidence that the artifact was approved, pinned, documented, and integrated according to the Supply Chain Security Standard.

5. Approved Python Runner Standard

The approved Python runner depends on the project transition state.

After the Python project manager is adopted in a repository, validation commands should prefer:

cd <workspace-root>/<repository>
uv run python -m py_compile path\to\file.py
uv run pytest
uv run ruff check .

During transition, existing local interpreter commands may still be used when they are the known working command for the repository:

cd <workspace-root>/<repository>
.\.venv\Scripts\python.exe -m py_compile path\to\file.py

Do not rewrite every validation command merely to use the future runner before the repository has adopted it. Record which runner was used in the handoff or output summary.

6. Documentation Validation

Markdown documentation is source material. Generated HTML should not be edited when a Markdown source is authoritative unless the task explicitly says to edit generated output.

For Markdown documents in the internal documentation library, validation should check:

frontmatter properties exist,
# Document Scope exists,
## 1. Purpose exists,
required title and slug are correct,
status and dates are current,
provider-neutral terms are used where appropriate,
selected implementation names appear in definition tables or implementation-specific sections,
forbidden hardcoded vendor/product names are avoided where generic language is required,
links or references are correct where practical,
git diff --check passes,
git status --short contains expected files only.

For context/reference repositories, documentation validation may also check:

required README or index files exist,
manifest or inventory files exist where that repository uses them,
source-summary files exist where that repository standard requires them,
Markdown/frontmatter structure is coherent enough for AI reference use,
obvious private secrets are absent,
link checks are run only when useful and not too noisy,
no deployment jobs exist or are expected.

For public-facing documents, also check customer-facing language, implementation-detail leakage, pricing/support accuracy, and whether the document exposes internal provider names unnecessarily.

7. Python Syntax, Import, and Package Validation

Python changes should run a syntax or compile check at minimum.

Use compile checks for changed Python files:

cd <workspace-root>/<repository>
uv run python -m py_compile path\to\file.py

or, during transition:

cd <workspace-root>/<repository>
.\.venv\Scripts\python.exe -m py_compile path\to\file.py

If import paths, package markers, package structure, or module locations changed, run import checks. Import checks should prove that active consumers can still load the moved module.

For package-boundary changes, validation should include:

consumer search,
compile checks,
direct import checks,
old-import search,
runtime contract verifier where available,
git diff --check,
git status --short.

A successful import does not prove runtime behavior. It only proves Python can load the module.

8. Linting and Formatting Validation

The linting and formatting layer should be used carefully during adoption.

For new code or scoped refactors, run lint checks when the repository configuration exists:

cd <workspace-root>/<repository>
uv run ruff check .
uv run ruff format --check .

If the repository has not yet adopted the tool, do not invent a configuration inside an unrelated task. Record that linting was not run because the repository has not yet adopted the linting and formatting layer.

Avoid broad formatting changes mixed with behavior changes. If formatting is applied broadly, it should be its own scoped commit or task so the diff does not hide behavior changes.

9. Testing Validation

The testing layer should protect behavior during refactoring.

When tests exist, run the narrowest relevant test first:

cd <workspace-root>/<repository>
uv run pytest tests\path\to\test_file.py

Then run broader tests only when the task scope justifies it.

For critical backend behavior, tests should eventually cover:

configuration loading,
environment separation,
database adapter behavior,
database access helpers,
service-layer workflows,
Telegram publishing safety,
deduplication,
operations incident creation,
remediation job behavior,
API request and response behavior,
auth integration boundaries,
scheduler and worker behavior.

Do not treat absence of tests as proof that no validation is needed. If tests do not exist, use targeted verifiers, dry-runs, import checks, no-mutation checks, or staging checks as appropriate.

10. Model and Configuration Validation

Model-layer changes should validate that expected inputs pass and incorrect inputs fail.

For Pydantic model changes, validation may include:

importing the model,
constructing valid examples,
checking required fields,
checking optional fields,
checking validation errors for invalid values,
checking serialization where API or storage behavior depends on it.

Configuration-layer changes require special care because they affect runtime behavior across environments.

For Pydantic Settings or configuration changes, validation should confirm:

local/staging/production environment identity,
required keys are defined,
safe defaults are safe,
secrets are not hardcoded,
missing required values fail clearly,
production is not the accidental default,
example files match code expectations,
local private files remain ignored and unstaged.

If a new runtime key is required, update the safe template when in scope. Do not commit private values.

11. API Layer Validation

API-layer changes should validate the route, model, and contract.

For FastAPI changes, validation may include:

route module import,
application import,
request model construction,
response model construction,
OpenAPI generation,
route tests through the test client,
auth/authorization boundary checks where applicable,
error response checks,
environment-specific behavior checks.

A useful API validation sequence is:

cd <workspace-root>/<repository>
uv run python -m py_compile path\to\api_file.py
uv run pytest tests\api

If no tests exist yet, create or run the smallest possible route import or OpenAPI generation check in the scoped task.

Internal API documentation should not be exposed publicly if it includes private or administrative routes.

12. Database Access Validation

Use provider-neutral database language in durable standards. The active repository may use a local or provider-managed SQLite-compatible database, an operations database, a content database, an authentication database, or another repository-specific database.

Database access changes should validate:

database identity,
staging/production separation,
connection behavior,
query execution,
parameter binding,
transaction behavior,
error handling,
query timing or logging where relevant,
no unintended writes,
expected row reads or writes in staging when approved.

For SQLAlchemy Core adoption tasks, validation should confirm that the new database access layer preserves existing query behavior before broader migration. Existing SQL statements may remain while connection, transaction, logging, or execution behavior is standardized.

Do not replace database behavior broadly as part of unrelated validation.

13. Schema Migration Validation

Schema migration changes are separate from ordinary query changes.

When the schema migration layer is in use, validate migrations against staging before production is considered.

A stage-first schema validation flow is:

1. Apply or test the migration against staging only.
2. Confirm the expected tables, columns, indexes, and constraints exist.
3. Insert a clearly marked synthetic row if write behavior must be tested.
4. Read the synthetic row and verify expected values.
5. Update or delete the synthetic row if that behavior is part of the migration test.
6. Confirm cleanup.
7. Confirm production was not changed unless the task explicitly approved production mutation.
8. Record rollback or downgrade behavior where practical.

Production migration is a separate operational event and requires explicit approval.

Manual database changes should be treated as emergency actions unless a documented task authorizes them.

14. Object Storage Validation

Object storage contains report artifacts, indexes, logs, generated reports, backup objects, exported files, and other objects whose database metadata may be separate from the stored object.

When a change affects object storage behavior, validate the lifecycle that the change touches:

1. Confirm the artifact metadata row exists when metadata is expected.
2. Confirm upload status is successful.
3. Confirm the bucket or container and object key are correct.
4. Confirm the stable access path can retrieve or open the artifact.
5. Confirm access is logged when access logging is part of the behavior.
6. Confirm missing, expired, or pruned objects produce a controlled unavailable state.
7. Confirm retention or cleanup behavior does not remove objects outside scope.

Durable user-facing or operator-facing links should use stable application routes or gateway routes rather than raw temporary provider URLs.

15. Stable Report Access Validation

Stable report access is the durable layer for report links, alert links, incident links, and operational artifact links. It hides raw temporary object URLs and gives users a controlled response when an artifact is missing, expired, or pruned.

When stable report access behavior changes, validate both successful and unavailable paths.

A successful path should reach the expected report or artifact.

A missing, expired, or pruned artifact should produce a controlled unavailable-report page or response and should provide a path to current reports, help, or recovery instructions when the user experience requires it.

Record the route, test artifact ID, expected result, actual result, and whether the access event was logged.

16. Runtime Worker and Monitoring Validation

Runtime worker validation should be short, targeted, and appropriate for the changed behavior.

Do not run long-lived workers, production schedulers, Watchdog, Deep Audit, or broad audits casually.

For processing-worker changes, useful validation may include:

brief controlled run,
start/stop behavior,
database row checks,
duplicate-output checks,
public-output quality checks,
token/provider-event checks when AI paths changed,
no-public-post confirmation where applicable.

For operations-worker changes, useful validation may include:

one focused worker run,
job-claim verification,
success path check,
failure path check,
job event check,
heartbeat check,
retry or terminal-state check.

The current monitoring scripts are:

Watchdog:   <workspace-root>/app/monitoring/watchdog.py
Deep Audit: <workspace-root>/app/monitoring/feed_audit.ps1

Watchdog is the lightweight monitor. It is intended for frequent operational health review. It can be useful for checking feed processor health, database reachability, Telegram identity/channel access, latest Deep Audit status, domain/DNS health, incident sync, and alert behavior where configured.

Deep Audit is the heavier audit. It is intended for deeper feed-quality, backlog, public-output, and operational evidence review. It produces report artifacts that may include HTML, text, and JSON outputs.

Watchdog and Deep Audit are troubleshooting and operational-baseline tools, not automatic startup commands for every session.

Run Watchdog when the task requires a lightweight operational baseline, when the handoff asks for it, when recent runtime health matters to the next decision, or when the user approves it.

Run Deep Audit when the task requires a deeper feed-quality or backlog review, when Watchdog points to a Deep Audit issue, when public-output quality or backlog risk is in scope, or when the user approves it.

If the task does not explicitly require Watchdog or Deep Audit, ask before running them.

If either tool is run, record:

tool name,
command used,
exit code,
overall PASS/WARN/FAIL status,
important WARN or FAIL lines,
summary/footer line,
generated report or log path,
whether email alerts, incidents, database writes, or external checks occurred or were expected.

If either tool is intentionally not run, record that fact and the reason.

The existing HTML monitoring runbooks remain useful background references but may be outdated in places. If exact current commands, schedules, report locations, or monitoring behavior matter to the task and the startup standards are not enough, ask for current monitoring documentation, current terminal output, or current repository state before implementing changes.

17. Scheduler Validation

The scheduler layer is not permanently tied to one scheduler tool.

Current validation may involve the current operating system’s scheduler because the project currently runs on Windows. Future validation may involve another scheduler after the project moves to a Linux VPS or a Python-native scheduling layer.

Scheduler validation should focus on behavior:

job name,
command,
working directory,
environment,
trigger timing,
enabled/disabled state,
last run result,
next run time,
log path,
worker identity,
retry behavior,
idempotency,
safe production behavior.

Do not change scheduler definitions during validation unless the task explicitly authorizes scheduler changes.

If a scheduler change is made, record the before and after state.

18. Telegram Pipeline Validation

Telegram is core product infrastructure.

Telegram-related changes can affect customer-facing output. Validate cautiously.

Validation may include:

raw intake path checks,
clean output path checks,
deduplication checks,
target channel identity,
dry-run or fake-call mode,
no-public-post confirmation,
rate-limit behavior,
retry behavior,
publication state,
post-publish verification,
operations logging.

Do not post to customer-facing channels unless the user explicitly authorizes a live publication test.

For AI-assisted processing changes, confirm that editorial quality and public/customer-facing news output are not reduced merely to satisfy a constrained AI quota.

19. Alert and Email Validation

Alerting changes need validation at two levels: rendering and delivery.

Rendering can usually be tested without sending a real message. Delivery tests may contact a provider, write database rows, or send real email, so they require the right task scope and approval.

A render-only test should confirm:

subject,
body,
links,
identifiers,
environment labels,
safety text,
recipient account reference where applicable.

A real delivery test should confirm:

delivery row status,
provider acceptance,
recipient confirmation when needed,
stable links,
dedupe behavior,
failure handling.

Do not fake production failures merely to test email. Before forcing another alert, inspect delivery rows and dedupe configuration so the test does not create duplicate notifications or confusing incident history.

20. Authentication and Bot-Protection Validation

Authentication-layer changes should validate account/session behavior through approved boundaries.

Python services should not duplicate authentication logic when the customer authentication layer is the source of truth. Validation should check integration boundaries, service tokens, validated claims, session-derived data, or API-level authorization as appropriate.

Bot-protection changes should validate that public forms still function for legitimate users and that failures produce understandable recovery paths.

For Turnstile Managed mode or other bot-protection changes, validate:

site key placement,
secret key storage,
backend token verification,
failure behavior,
retry behavior,
logging,
rate-limit interaction,
accessibility,
mobile behavior,
VPN or hardened-browser behavior where practical,
privacy-policy references where required.

Do not log unnecessary personal data during bot-protection validation.

21. Frontend and Static Site Validation

Static site changes should validate source files and rendered output where practical.

For static pages, validate:

HTML structure,
CSS behavior,
JavaScript syntax,
links,
responsive layout where relevant,
public/customer-facing wording,
absence of internal implementation leakage,
generated output if Markdown publishing is involved.

Dynamic frontend application changes should validate:

build or type check,
component rendering,
API client behavior,
auth boundary behavior,
state handling,
forms,
charts,
accessibility,
error states,
environment labels for admin tools.

Frontend clients should consume APIs. They should not access databases directly.

22. Internal Dashboard and Terminal Tool Validation

Internal dashboard changes should validate both display and data source boundaries.

For internal browser dashboards, validate:

dashboard import/startup,
read-only versus mutating behavior,
environment labels,
database/service calls through approved layers,
safe handling of production data,
empty/error states,
auth or internal access assumptions.

For terminal output tools, validate:

command startup,
exit code,
readable output,
correct environment label,
no hidden mutation,
summary markers where needed.

For interactive terminal applications, validate keyboard navigation, startup/shutdown behavior, data source calls, and safe handling of write-capable actions.

23. Configuration and Secrets Validation

Configuration examples and local runtime configuration have different safety rules.

A configuration example may be committed when it contains placeholders, safe defaults, and documented keys.

A local runtime config file or secrets file must not be committed.

Useful validation includes:

1. Confirm no private token, password, API key, bearer token, SMTP credential, customer secret, webhook secret, or auth secret appears in tracked files.
2. Confirm placeholders are clearly marked.
3. Confirm example keys match the code that reads them.
4. Confirm local private config remains ignored and unstaged.
5. Confirm generated logs, caches, databases, dependency folders, and virtual environments are not commit candidates.

Secret scanning should be targeted to the changed files and relevant generated exports. Do not broaden the scan into unrelated private directories unless the task explicitly asks for that inspection.

24. Public Output Quality Validation

Changes that can affect public or customer-facing output require quality validation.

This applies to:

clean Telegram posts,
public website text,
customer dashboard text,
pricing or plan language,
support documents,
public documentation,
transactional emails,
alerts shown to users,
generated reports shared outside the operator workflow.

Validation should confirm that public output is accurate, readable, appropriately scoped, and not degraded by cost-saving, token-saving, formatting, provider, or automation changes.

Efficiency improvements are allowed. Public/customer-facing output quality must not be silently reduced to fit a constrained AI quota or convenience goal.

25. Environment and Production-Safety Validation

Any tool that can write data must make environment identity visible.

Production should never be the accidental default for scripts that can mutate data.

Before a production-adjacent validation, confirm:

repository,
branch,
environment,
database target,
provider target,
Telegram channel target,
object storage target,
email recipient,
scheduler target,
whether the command writes data,
whether the user approved the write.

If a command can mutate production, send messages, publish content, alter scheduler definitions, or modify provider resources, classify it before running and require explicit approval.

26. Output Summary Standard

Validation commands should end with a compact output summary when the user needs to paste terminal output into another AI session.

The summary should include:

important exit codes,
generated log paths,
changed file paths,
validation result markers,
skipped checks,
git diff --stat,
git status --short.

A useful output summary does not paste thousands of unrelated log lines. It selects the evidence needed for the next decision.

Example pattern:

Write-Host ""
Write-Host "***** BEGIN OUTPUT SUMMARY *****"
Write-Host "VALIDATION_EXIT=$validationExit"
Write-Host "DIFF_CHECK_EXIT=$diffCheckExit"
Write-Host "VALIDATION_LOG=$validationLog"
Write-Host "KEY_RESULTS:"
Select-String -Path $validationLog -Pattern "VERIFY_PASS|VERIFY_FAIL|RUNTIME_PASS|RUNTIME_FAIL|RUNTIME_CONTRACT_PASS|RUNTIME_CONTRACT_FAIL"
Write-Host "GIT_DIFF_STAT:"
git diff --stat
Write-Host "GIT_STATUS:"
git status --short
Write-Host "***** END OUTPUT SUMMARY *****"

If the validation includes database checks, include compact row identifiers, statuses, and timestamps rather than full query dumps. If it includes Watchdog or Deep Audit output, include the relevant check line and final summary or footer line rather than the whole log.

27. CI/CD Pipeline Validation

CI/CD validation is the remote repository validation layer.

Local validation and CI/CD validation are separate gates. Local validation proves that the current working tree behaves correctly in the local environment. CI/CD validation proves that the remote repository can reproduce the required checks in a clean pipeline environment.

Pipeline validation depends on repository class.

For deployable repositories, CI/CD validation may eventually include linting, tests, builds, artifacts, staging deployment, and manually gated production deployment.

For the server/infrastructure repository, CI/CD validation should begin with configuration checks, script syntax checks, service-definition checks, scheduled-job definition checks, tunnel configuration checks where practical, and dry-runs. It must not mutate production infrastructure unless explicitly approved.

For context/reference repositories, CI/CD validation should remain minimal. It may include Markdown/frontmatter checks, required README or index checks, manifest or inventory checks where present, no-secret checks, file-size sanity checks where useful, and link checks where useful. It should not include deployment, database migration, runtime application tests, customer-facing deployment, or production environment jobs.

Context/reference validation must distinguish a real repository problem from a validation-rule problem. A pipeline can fail because the content is wrong, because the shell command is fragile, because a runner environment differs from the local environment, or because a no-secret rule is too broad for documentation that legitimately discusses credentials. The failed job log must be reviewed before changing repository code or weakening validation.

When a repository has a configured pipeline, pipeline status should be reviewed after push before the remote branch is treated as validated. For branch work that will merge into main, validation is not complete until the branch pipeline has been reviewed before merge and the main pipeline has been reviewed after merge.

When a change affects dependencies, tooling, tests, package layout, scripts, build steps, runtime commands, frontend build behavior, deployment behavior, database migration behavior, validation commands, environment variables, secrets, documentation structure, reference-library structure, or repository structure, the session must consider whether the pipeline configuration should be updated.

For pipeline configuration changes, validation should include:

repository class,
pipeline configuration syntax review,
expected stages and jobs,
expected runner environment,
dependency setup behavior,
lint/test/build/documentation commands as relevant,
artifact behavior where relevant,
cache behavior where relevant,
environment and variable references,
confirmation that production deployment is not automatic unless explicitly approved,
confirmation that context/reference repositories have no deployment jobs,
expected pipeline behavior after push.

For early pipeline adoption, validation should begin with low-risk jobs such as lint, compile, tests, static build, documentation checks, reference-library checks, or no-secret checks. Do not begin with production deployment automation.

Pipeline configuration is high-impact repository code. It can run commands, consume secrets, publish artifacts, deploy services, modify infrastructure, run database migration commands, or mutate environments. Do not create or modify pipeline configuration unless the task explicitly scopes that work.

A validation summary for repository work should include CI/CD impact:

Pipeline impact:
- Repository class:
- Pipeline file changed: yes/no.
- Pipeline update needed: yes/no/deferred.
- Reason:
- Expected pipeline behavior after push:
- Deployment expected: yes/no.

If no pipeline exists yet, record whether a minimal validation pipeline should be created as a follow-up.

Architectural Impact Review Standard

Repository work must include an Architectural Impact Review before commit readiness. The review is broader than CI/CD. CI/CD pipeline impact remains mandatory, but it is one part of a larger checkpoint that asks whether the completed work changed, weakened, contradicted, or exposed anything else that should be fixed before the repository checkpoint is created.

The Architectural Impact Review is not merely an information-gathering exercise. After the review identifies an affected area, the assistant or coding agent must decide whether the issue can be addressed safely inside the current task scope before the commit. If it can be fixed safely and the file scope allows it, the fix should be made and validated before commit. If it cannot be fixed safely, is outside the approved file scope, requires operator approval, touches production, requires a separate branch, or would mix unrelated work into the checkpoint, it must be recorded as a generated follow-up task with enough context for a future human, AI session, automation worker, or operations database process to act on it.

Before commit readiness, ask the following questions in full and answer them based on the actual diff, validation output, repository class, and task scope:

Did dependencies, dependency groups, lockfiles, package manager configuration, Python version files, Node package files, or build-tool files change?
Did the approved Python runner, script execution method, project metadata, virtual environment assumptions, or local setup instructions change?
Did linting, formatting, type-checking, test discovery, test commands, test fixtures, or validation commands change?
Did package layout, module layout, imports, entry points, service boundaries, script locations, or runtime command paths change?
Did startup commands, worker commands, scheduler commands, service names, process names, ports, hostnames, tunnels, local preview routes, or health-check routes change?
Did configuration loading, settings models, environment identity, environment variables, example configuration files, secret names, protected variables, or ignored private files change?
Did database access, query behavior, transaction handling, schema, migration files, seed data, staging/production separation, or database safety assumptions change?
Did object storage behavior, report artifact paths, stable links, retention behavior, backup behavior, archive behavior, or recovery procedures change?
Did API routes, request models, response models, authentication checks, authorization checks, OpenAPI output, dashboard contracts, or frontend/backend integration expectations change?
Did frontend build behavior, static-site generation, public assets, internal dashboard behavior, browser-visible routes, accessibility behavior, or customer-facing copy change?
Did Telegram intake, processing, deduplication, AI rewriting, delivery, channel routing, customer-visible output quality, or provider-call behavior change?
Did email, alerting, notifications, operational reports, incident creation, remediation jobs, or AI-agent work queues change?
Did monitoring, Watchdog, Deep Audit, logs, metrics, operations records, health checks, failure reporting, or observability expectations change?
Did deployment behavior, release behavior, rollback behavior, staging behavior, production behavior, infrastructure mutation, or manual deployment gates change?
Did repository structure, documentation structure, context/reference library structure, generated documentation, README material, runbooks, handoff files, or operator procedures change?
Did CI/CD pipeline configuration, pipeline stages, jobs, images, caches, artifacts, runner assumptions, pipeline variables, protected variables, deployment gates, or expected pipeline behavior after push change?
Did Docker, Compose, container build assumptions, .dockerignore, image startup commands, container environment variables, mounted paths, exposed ports, health checks, or container validation need to be created or updated because of the work?
Did Kubernetes, service manifests, deployment manifests, secrets handling, config maps, ingress, jobs, cron jobs, probes, namespaces, or cluster deployment assumptions need to be created or updated because of the work?
Did the work create or reveal any security, privacy, access-control, secret-handling, production-safety, customer-impact, or data-retention concern?
Did the work create or reveal any documentation mismatch, stale standard, stale runbook, stale local command, stale Codex prompt template, stale validation command, or stale startup instruction?
Did the work reveal a repetitive manual step that should become a helper script, verifier, CI/CD job, documentation rule, runbook step, or future automation-worker task?
Did the work reveal a weakness, ambiguity, missing safeguard, or process gap in the project standards, repository workflow, validation model, commit-message model, or AI-agent operating instructions?
Which of the identified issues can be fixed safely before this commit without broadening the task improperly?
Which identified issues must be recorded as generated follow-up tasks, and what exact future action should be taken?
What should the operations database or future AI-worker layer be able to extract from this checkpoint?

Use this compact review format before commit readiness:

Architectural impact review:
- Repository class:
- Runtime behavior changed: yes/no.
- Validation behavior changed: yes/no.
- Configuration or secrets changed: yes/no.
- Database or persistent state changed: yes/no.
- API, frontend, dashboard, or customer-visible contract changed: yes/no.
- Monitoring, operations, reports, or AI-agent records changed: yes/no.
- CI/CD impact: yes/no.
- Docker impact: not adopted/no/yes/follow-up.
- Kubernetes impact: not adopted/no/yes/follow-up.
- Deployment or infrastructure impact: yes/no.
- Documentation or runbook impact: yes/no.
- Immediate fixes made before commit:
- Follow-up tasks generated:
- Reason unresolved items were deferred:

The review must be written in full, human-readable sentences when entered into a commit message, merge commit message, Codex handoff, or state handoff. Short labels may be used in the pre-commit working summary, but the durable record must preserve enough context for later recovery, operations database ingestion, and future AI-agent action.

Workflow Weakness and Safeguard Review

Every commit must explicitly answer this question:

Has this commit revealed a weakness, ambiguity, missing safeguard, or repetitive manual step in the project standards or workflows?

This answer must not be buried inside a generic risk section. It must be recorded as its own subsection in the commit message or merge commit message. If the answer is yes, the assistant or coding agent must identify what created the weakness, where it exists, why it matters, whether it was remediated before commit, and what follow-up remains. If the answer is no, the durable record must say that no workflow weakness, ambiguity, missing safeguard, or repetitive manual step was identified from this change.

When a weakness or repetitive manual step is identified, the assistant must immediately ask whether it can be safely fixed before commit. The default action is to fix it now when the fix is inside scope, low risk, validated, and does not mix unrelated work into the checkpoint. If the fix is not safe to include now, it must become a generated follow-up task, not an informal note.

28. Commit Readiness

Commit readiness includes record readiness. A change is not ready to commit, push, or merge if the intended commit or merge message does not preserve the operational context required by the Git Commit Message Standard. For work expected to feed operations database records, future AI repair workflows, or MCP-accessible project context, the message body is part of the validated artifact.

Before pushing main after a local merge, inspect the merge commit body with:

git show --no-patch --format=full HEAD

If the message is incomplete, corrupted, or generic and the commit has not been pushed, amend it before push. If the defective commit has already been pushed to protected main, repair forward with a corrective documentation or audit commit.

Runtime validation feeds into Git commit readiness, but it does not replace Git review.

Before a commit is recommended, confirm:

1. Relevant validation passed or skipped validation is justified.
2. Changed files match the task scope.
3. git diff --check passes.
4. git diff --stat is understood.
5. git status --short contains only expected files.
6. Local config, secrets, logs, databases, temp files, virtual environments, provider-local caches, and dependency folders are not commit candidates.
7. CI/CD pipeline impact has been reviewed for repository changes.
8. Any handoff file records exact validation output, pipeline impact, and remaining risk.

If required runtime validation fails, do not hide the failure with cleanup and do not recommend a commit. Determine whether the code is wrong, the verifier is stale, the data needs targeted repair, or the validation plan needs a corrected rerun.

29. Handoff Requirements

A validation-sensitive task should record validation in a handoff when the result needs to persist across sessions.

The handoff should include:

task completed,
files changed,
validation commands run,
exact validation output or compact output summary,
checks intentionally not run,
network calls made or avoided,
database mutations made or avoided,
Telegram posts made or avoided,
production resources touched or avoided,
remaining risks,
final git status,
repository class,
CI/CD pipeline impact and expected pipeline behavior after push.

If a validation command initially fails and then passes after correction, record both facts.

Skipped checks should not be hidden. They should be explained.

30. Future AI Session Instruction Block

Future AI sessions may copy the following instruction block when validating repository changes.

You are validating changes in a named repository inside the modular workspace. Confirm the repository path, branch, and working-tree state before recommending a commit, push, merge, restore, revert, or recovery action.

Choose validation based on the behavior affected by the change. Syntax checks are necessary for code but are not enough when runtime behavior, database state, object storage, report access, API contracts, configuration, schedulers, alerting, Telegram behavior, public output, or production safety changed.

Use durable <workspace-root>/<repository> notation in documentation. Use current-machine literal paths only for commands that are clearly labeled as current-machine commands.

Use the approved Python runner for the repository. After uv adoption, prefer uv run. During transition, existing local interpreter commands may still be valid.

Do not run production mutations, Watchdog, Deep Audit, live delivery tests, broad audits, expensive runtime jobs, or production deployment pipeline jobs unless the task requires them or the user approves them. Watchdog and Deep Audit are the current monitoring scripts; ask before using them unless the task-specific handoff explicitly calls for them.

Record exact validation output, skipped checks, risks, network calls, database mutations, Telegram posts, production resources touched, repository class, CI/CD pipeline impact, expected pipeline behavior after push, and final git status in the handoff.

31. Review Triggers

Review this document when:

1. The Python project manager is adopted in a repository.
2. The linting and formatting layer is configured.
3. The testing layer is established.
4. The API layer is implemented.
5. The model layer is introduced broadly.
6. The configuration layer is centralized.
7. The database access layer is standardized.
8. Schema migration tooling is adopted.
9. The scheduler strategy changes.
10. Watchdog or Deep Audit behavior, schedule, output format, or report paths change.
11. The project moves from Windows to Linux.
12. Object storage access patterns change.
13. Authentication or bot-protection behavior changes.
14. Telegram publishing behavior changes.
15. Future AI agents begin automated operations.
16. A repository is added, reclassified, or repurposed.
17. A repository adopts or materially changes a CI/CD pipeline.
18. Production incidents reveal missing validation coverage.