@tera-system/core 0.1.0

package/core/tera-system/engineering-governance/ENGINEERING_GOVERNANCE_GATE.md

@@ -0,0 +1,131 @@
+# ENGINEERING_GOVERNANCE_GATE.md
+
+## Tera Engineering Governance Gate
+
+| Metadata | |
+|---|---|
+| **Status** | Active system gate |
+| **Source** | `tera-system/engineering-governance/ENGINEERING_BEST_PRACTICES.md` |
+| **Used By** | Tera Pre-Execution Gate, Post-Execution Review, Engineering agents, Auditor, Monitor, QA |
+| **Last Updated** | 2026-07-01 |
+
+---
+
+## 1. Purpose
+
+This gate turns engineering best practices into operational checks before and after implementation tasks.
+
+It does not replace:
+
+- `TeraPreExecutionGate.md`;
+- active Technology Profiles;
+- Design Governance;
+- Security review;
+- QA acceptance review.
+
+It adds maintainability and architecture checks to prevent structural decay.
+
+---
+
+## 2. When the Gate Applies
+
+Apply this gate when a task creates or modifies any of the following:
+
+- application source code;
+- modules/features;
+- UI components with logic;
+- API/server actions/controllers;
+- services/use cases/domain rules;
+- validation logic;
+- permissions/security checks;
+- database schema/migrations/repositories;
+- shared utilities/components;
+- tests;
+- architecture or coding standards.
+
+For documentation-only edits, apply only if the document defines engineering rules.
+
+---
+
+## 3. Project Size Adjustment
+
+| Project Level | Gate Strictness |
+|---|---|
+| Compact | Check obvious bloat, module clarity, no UI/business logic mixing for important rules |
+| Standard | Check module boundaries, service/use-case separation, validation, permissions, tests when needed |
+| Full | Check layered architecture, cross-module coupling, audit/logging, performance, integration boundaries, stronger tests |
+
+Do not force Full architecture on Compact projects unless approved by Tera and the user.
+
+---
+
+## 4. Pre-Execution Checks
+
+Before approving or delegating an implementation task, Tera must verify:
+
+| # | Check | Required Result |
+|---|---|---|
+| 1 | Does the task identify the affected module or shared/core area? | Yes / N/A |
+| 2 | Is the task small enough to avoid architectural mixing? | Yes |
+| 3 | Could the task create a file likely to exceed responsibility or size limits? | No / Mitigated |
+| 4 | Is business logic kept out of UI where applicable? | Yes / N/A |
+| 5 | Is module-specific logic kept out of `shared/`? | Yes / N/A |
+| 6 | Are validation rules placed at the correct layer? | Yes / N/A |
+| 7 | Are permissions enforced outside frontend when relevant? | Yes / N/A |
+| 8 | Are database changes traceable through the approved migration/schema task path? | Yes / N/A |
+| 9 | Are API response/error expectations consistent with the project? | Yes / N/A |
+| 10 | Are tests required for important logic? If yes, are they in scope or deferred with reason? | Yes / N/A |
+| 11 | Does the task avoid unnecessary libraries, folders, abstractions, or docs? | Yes |
+| 12 | Does the task reference active Technology Profile rules when stack-specific structure matters? | Yes / N/A |
+| 13 | Does the task introduce generic or vague naming patterns (`helper`, `common`, `manager`, `data`)? | No / N/A |
+| 14 | If the task involves external API calls, are timeout and error-handling defined? | Yes / N/A |
+| 15 | If the task involves sensitive write operations (payment, order, invoice), is idempotency considered? | Yes / N/A |
+
+If a required check fails, the task cannot receive `Pre-Execution Gate: PASS` until corrected, split, or explicitly approved as a documented exception.
+
+---
+
+## 5. Post-Execution Checks
+
+Before accepting or closing an implementation task, Tera or an independent reviewer must verify:
+
+| # | Check | Required Result |
+|---|---|---|
+| 1 | Changed files are in the approved module/shared/core targets. | Yes |
+| 2 | No file became obviously multi-responsibility or oversized without reason. | Yes |
+| 3 | UI code did not absorb business rules that belong in services/use cases/domain. | Yes / N/A |
+| 4 | Shared utilities/components were not used as dumping grounds. | Yes |
+| 5 | Validation exists at backend/service/API layer when required. | Yes / N/A |
+| 6 | Permissions are not frontend-only when security matters. | Yes / N/A |
+| 7 | Database changes match the approved schema/migration scope. | Yes / N/A |
+| 8 | API/error behavior is consistent with project standards. | Yes / N/A |
+| 9 | Important logic has tests, or missing tests are recorded as an issue/deferred item. | Yes / Deferred with reason |
+| 10 | No unnecessary abstractions, libraries, or folders were introduced. | Yes |
+| 11 | Any engineering deviation is recorded in task review, `ISSUES_AND_GAPS.md`, or `DECISIONS_LOG.md` as appropriate. | Yes / N/A |
+| 12 | New or changed files follow clear naming conventions without generic dumping-ground names. | Yes / N/A |
+| 13 | External service integrations handle timeouts, retries, and failure gracefully. | Yes / N/A |
+| 14 | Sensitive write operations are idempotent or implement deduplication. | Yes / N/A |
+
+---
+
+## 6. Failure Results
+
+| Result | Meaning | Required Action |
+|---|---|---|
+| PASS | Engineering structure is acceptable for the project level | Continue review/acceptance path |
+| NEEDS_FIX | Issue can be corrected within same task scope | Return to responsible agent with exact fixes |
+| BLOCKED | Requires user/Tera decision, architecture change, or task split | Stop affected task and record blocker |
+| DEFERRED_WITH_RECORD | Not blocking now, but must be tracked | Record in `ISSUES_AND_GAPS.md` or future task |
+
+---
+
+## 7. Exception Rule
+
+Engineering ideals may be relaxed only when:
+
+- the project is intentionally Compact;
+- the task is a limited scaffold or spike;
+- the exception is temporary and recorded;
+- Tera documents the reason and follow-up if needed.
+
+Unrecorded exceptions are not valid.

package/core/tera-system/engineering-governance/ENGINEERING_REVIEW_CHECKLIST.md

@@ -0,0 +1,129 @@
+# ENGINEERING_REVIEW_CHECKLIST.md
+
+## Engineering Review Checklist
+
+| Metadata | |
+|---|---|
+| **Status** | Active checklist |
+| **Used By** | Auditor, Tera, Monitor, QA, Engineering reviewers |
+| **Source** | `ENGINEERING_BEST_PRACTICES.md` + `ENGINEERING_GOVERNANCE_GATE.md` |
+| **Last Updated** | 2026-07-01 |
+
+---
+
+## 1. Review Scope
+
+Use this checklist when reviewing code, implementation batches, task outputs, or release readiness.
+
+Review only the relevant areas. Do not expand a small review into a full audit unless Tera or the owner asks for it.
+
+---
+
+## 2. Architecture and Structure
+
+- [ ] Modules/features are clear.
+- [ ] Code is not organized only by random generic folders.
+- [ ] `core/`, `shared/`, and `modules/` boundaries are respected where applicable.
+- [ ] Module-specific logic is not placed in `shared/`.
+- [ ] Cross-module dependencies are intentional and not circular/random.
+- [ ] New abstractions are justified by current need, not speculation.
+
+---
+
+## 3. File and Responsibility Health
+
+- [ ] No changed file is clearly handling unrelated responsibilities.
+- [ ] Files approaching `300–400` lines are reviewed for responsibility creep.
+- [ ] Functions/components have clear names and one primary purpose.
+- [ ] Large orchestration functions are split into readable operations when useful.
+
+---
+
+## 4. UI / Application / Domain Separation
+
+- [ ] UI components are not owners of business rules.
+- [ ] Important business operations live in services/use cases/domain/rules according to project size.
+- [ ] Data mapping/formatting is separated when it becomes non-trivial.
+- [ ] UI changes do not introduce hidden API/security/database behavior.
+
+---
+
+## 5. Shared Code and DRY
+
+- [ ] Shared code is genuinely shared by more than one module.
+- [ ] No `utils` dumping ground was created or expanded without structure.
+- [ ] Duplicate logic is left, watched, or extracted according to practical repetition and risk.
+- [ ] Extracted helpers have clear names and narrow responsibility.
+
+---
+
+## 6. Validation, Errors, and Permissions
+
+- [ ] Validation is not frontend-only when data integrity matters.
+- [ ] Backend/API/service validation exists for important inputs.
+- [ ] Error format and messages follow project conventions.
+- [ ] Permissions are enforced beyond UI hiding when security matters.
+- [ ] Security-sensitive changes are escalated to SecurityAgent or Tera as required.
+
+---
+
+## 7. Database and API
+
+- [ ] Database schema changes match the approved task and migration strategy.
+- [ ] No manual or untraceable database change is implied.
+- [ ] Naming and relations are clear.
+- [ ] Indexes/pagination are considered for important query paths.
+- [ ] API response and error behavior is consistent.
+
+---
+
+## 8. Testing and Acceptance
+
+- [ ] Important business rules have tests or a documented reason for deferral.
+- [ ] Permission and validation behavior is testable.
+- [ ] API or integration behavior has appropriate verification.
+- [ ] UI/E2E tests are used only when they add justified confidence.
+- [ ] Acceptance criteria are mapped to actual output.
+
+---
+
+## 9. Documentation and Decisions
+
+- [ ] Architecture-affecting changes are documented.
+- [ ] Deviations are recorded in `DECISIONS_LOG.md` or task review notes.
+- [ ] Risks/gaps are recorded in `ISSUES_AND_GAPS.md`.
+- [ ] The task handback names changed files and meaningful decisions.
+
+---
+
+## 10. Naming and Code Standards
+
+- [ ] File, function, and variable names express purpose clearly.
+- [ ] No generic names like `helper`, `common`, `manager`, `data`, `process`, or `handle`.
+- [ ] Naming style is consistent within the project (camelCase / PascalCase / snake_case).
+- [ ] File names match their primary export or responsibility.
+
+---
+
+## 11. External Integration and Idempotency
+
+- [ ] External calls have explicit timeouts and retry limits.
+- [ ] Service failures are handled gracefully without crashing the system.
+- [ ] Sensitive write operations (payments, orders, invoices) are idempotent or use request-id deduplication.
+- [ ] Race conditions on shared records are handled with locking or transactions.
+
+---
+
+## 12. Review Output Classification
+
+Classify every finding as one of:
+
+| Classification | Meaning |
+|---|---|
+| Must Fix Now | Blocks acceptance or creates serious maintainability/security risk |
+| Should Fix Soon | Important but can be scheduled safely |
+| Defer With Record | Not blocking current phase, must be tracked |
+| Observation | Useful note, no action required now |
+| Not Applicable | Outside current review scope |
+
+Auditors and reviewers must not turn every observation into a blocking issue.

package/core/tera-system/engineering-governance/QUALITY_GATE_THRESHOLDS.md

@@ -0,0 +1,159 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# QUALITY_GATE_THRESHOLDS.md
+
+## 1. Purpose
+
+This file defines default quality-gate rule classes, evidence requirements, and P1/P2 thresholds for Auditor.
+
+It is a reference for `.opencode/agents/auditor.md` and must not be treated as a universal automatic pass/fail table.
+
+Core rule:
+
+```text
+Threshold exceeded = finding candidate.
+Severity depends on impact, context, confidence, evidence quality, and whether the issue is new in the diff.
+```
+
+## 2. Rule Classes
+
+| Rule Class | Meaning | Examples | Blocking Behavior |
+|---|---|---|---|
+| Hard rules | Direct safety/security/governance failures | secrets, unredacted credentials, unsafe raw query with user input, unauthorized permission expansion | May produce STOP |
+| Default heuristics | Useful indicators, not universal failures | file size, function size, parameter count, nesting, TODO count | Finding only; context decides severity |
+| Project-calibrated rules | Need artifact, baseline, language, or analyzer | coverage, duplication %, churn, CBO, vulnerability status | Cannot be asserted without evidence |
+
+## 3. Evidence Requirements
+
+| Finding Type | Required Evidence |
+|---|---|
+| File/function size | Direct file read is enough |
+| Function complexity | Analyzer report, AST evidence, or clearly traceable manual reasoning |
+| Duplication percentage | Static analyzer report only; otherwise call it suspected duplication |
+| Coverage | QA report or coverage artifact only |
+| Flaky tests | QA/CI history only |
+| Vulnerable dependency | SecurityAgent report, dependency scanner, or authoritative advisory |
+| Dependency freshness | Not a finding by itself; require vulnerability, EOL, incompatibility, or unused dependency |
+| Technical Debt Ratio | Tool report only |
+| CBO/coupling metric | Analyzer or explicit dependency evidence |
+| Circular dependency | Analyzer or clear import-chain evidence |
+| Code churn | Git history evidence |
+| Semgrep scan finding | Semgrep CLI output (`semgrep --config=tera-system/semgrep-rules/ --metrics=off <files>`) or MCP scan result; must include rule ID, file:line, severity |
+| Playwright screenshot | Screenshot file path with timestamp; must show the full page or specific element |
+| Playwright E2E test | JSON report output from `npx playwright test --reporter=json` |
+| Trivy scan result | JSON output from `trivy fs --scanners vuln,secret,misconfig --format json .` |
+| Gitleaks scan result | Output from `gitleaks git . --redact --no-banner` or `gitleaks detect --source . --redact --no-banner`; must include leak type, file, and whether it is a real credential |
+| Axe accessibility finding | Output from `@axe-core/playwright` `analyze()` inside a Playwright test; must include violation id, impact, nodes affected |
+| Testcontainers integration test | Test report showing services started via Testcontainers (PostgreSQL/Redis/etc.), migration applied, and assertions run against the real service |
+
+## 4. Default Heuristics
+
+These are default signals, not hard failures.
+
+| Metric | Flag Candidate | Caution Candidate | Notes |
+|---|---:|---:|---|
+| Function length | 50+ lines | 100+ lines | Context matters; generated or algorithmic code may differ |
+| File length (production) | 300+ lines | 500+ lines | New large files need stronger justification. Context override: files that exceed the Caution threshold but are structurally coherent (single responsibility, cohesive domain, no unrelated concerns mixed in) may be classified as FLAG instead of Caution. The heuristic is a signal for review, not an automatic severity. |
+| Parameter count | 7+ | 10+ | Prefer parameter object or clearer data model where appropriate |
+| Nesting depth | 4+ | 6+ | Manual readability signal |
+| TODO/FIXME/HACK in changed code | any | repeated or critical path | Must distinguish temporary note from hidden debt |
+| Suspected duplication | visible repeated block | repeated business logic | No percentage without analyzer |
+| Semgrep WARNING in new code | any new | repeated across files | Not automatic CAUTION; context matters |
+| Semgrep INFO in new code | any new | — | Not a finding by itself |
+| PLAYWRIGHT_UI_CHECK skipped | any UI change | repeated | Not automatic CAUTION; documented reason required |
+| UI component written from scratch | component exists in shadcn/ui or Teranoo Registry | repeated across files | FLAG — استخدم shadcn/ui أو Teranoo UI Registry بدل إعادة الاختراع |
+| Trivy misconfig (MEDIUM+) in IaC/Docker | any new | repeated | FLAG or CAUTION depending on context |
+| API بدون Bruno collection | API endpoints new/changed | repeated across tasks | FLAG — وثّق APIs باستخدام Bruno |
+| إنتاج بدون Sentry | App delivery-ready | — | FLAG — أضف Sentry SDK للمراقبة |
+| GITLEAKS_PRE_DELIVERY_CHECK skipped | Auth/Payment/Secrets/PII task | repeated | Not automatic CAUTION; documented reason required |
+| Axe violation in NEW UI code | new UI flow/component | repeated across files | CAUTION if serious (missing labels, low contrast, broken ARIA); FLAG otherwise |
+| Axe violation in pre-existing UI (outside diff) | unrelated old UI | — | BASELINE_DEBT — no task block unless the diff worsens it |
+| Integration test relying only on Mocks when Docker is available | data-layer change | repeated | FLAG — استخدم Testcontainers للخدمات الحقيقية حيث أمكن |
+
+## 5. Hard Rule Examples
+
+| Rule ID | Condition | Typical Severity |
+|---|---|---|
+| QG-SEC-001 | Real secret or credential in code/task/log/report | STOP |
+| QG-SEC-002 | Unredacted connection string outside approved local env files | STOP |
+| QG-SEC-003 | Unsafe raw query or string-concatenated query using user input | STOP / CAUTION |
+| QG-SEC-004 | Unsafe eval/command execution/deserialization in changed code | STOP / CAUTION |
+| QG-GOV-001 | Unauthorized permission expansion or scope expansion in changed work | STOP / CAUTION |
+| QG-ARCH-001 | New circular dependency proven by import chain or analyzer | CAUTION / STOP if architecture-critical |
+| QG-DB-001 | Migration Down() is not the inverse of Up() (e.g., drops index/constraint/column never created by Up()) | STOP |
+| QG-DB-002 | Migration alters data in a way that cannot be reversed (destructive UPDATE/DELETE without backup logic) | STOP / CAUTION |
+| QG-SEC-005 | Semgrep ERROR finding (new in diff) — confirmed true positive by Auditor | STOP / CAUTION |
+| QG-SEC-007 | Trivy CRITICAL vulnerability in production dependency | STOP |
+| QG-SEC-008 | Trivy secret finding — confirmed real credential | STOP |
+| QG-SEC-009 | Trivy HIGH vulnerability in production dependency without patch or mitigation | CAUTION |
+| QG-SEC-010 | Gitleaks finding — confirmed real credential in Git history or files | STOP |
+| QG-SEC-011 | Gitleaks finding — test/demo credential introduced by this task (not pre-existing/documented) | STOP / CAUTION |
+| QG-SEC-006 | Agent bypassed SEMGREP_SANITY_CHECK without documented reason in handback | CAUTION |
+
+## 6. Testing Adequacy Rules
+
+Auditor does not run tests.
+
+Review questions:
+- Did behavior change?
+- Are relevant tests present or clearly not applicable?
+- Is there QA evidence when acceptance requires execution?
+- Are normal, failure, and edge paths covered where relevant?
+- Is critical logic changed without visible test evidence?
+
+Avoid hard use of test-to-code ratio. It is only an advisory smell and can be gamed.
+
+`Zero assertions` is not automatically STOP because snapshots, property-based tests, exception tests, fixtures, and setup files require context.
+
+## 7. UI Code Accessibility Baseline
+
+Use code-level checks only:
+- missing accessible name for interactive controls
+- non-semantic interactive elements without keyboard support
+- missing/incorrect label-field relationship
+- incorrect/conflicting ARIA
+- missing focus/loading/error/disabled-state handling where relevant
+
+Do not require ARIA where semantic HTML already provides the correct role/name/value.
+
+## 8. Diff-First and Baseline Debt
+
+Auditor reviews changed code first. Existing debt outside the diff is `BASELINE_DEBT`.
+
+Do not block a task for unrelated baseline debt unless it is critical and the current change exposes, worsens, or relies on it.
+
+Escalation: When a diff materially changes a component that already has a baseline gap (e.g., accessibility, error handling), and the change worsens the gap's impact or exposure, the Auditor may escalate the finding from BASELINE_DEBT to CAUTION or higher. Example: A modal with no focus trap that is expanded from 3 to 5 steps — the baseline gap now affects more user flows and is harder to escape.
+
+## 9. Audit Modes
+
+| Mode | Use When | Scope |
+|---|---|---|
+| Documentation | Documentation-only change | governance/document consistency |
+| Light | config/small code | P1 + relevant P2 checks |
+| Standard | normal feature/UI change | P1 + P2 plus applicable quality domains |
+| Full Risk-Based | architecture/security-sensitive | expanded risk-based review of all applicable domains; not exhaustive proof |
+
+## 10. Architecture and File-Structure Rule Examples
+
+Apply these during P3 Architecture and File-Structure Audit for Standard and Full Risk-Based audits.
+
+| Rule ID | Condition | Typical Severity |
+|---------|-----------|-----------------|
+| QG-ARCH-002 | Changed code places business rules in UI/page/component when service/domain layer exists or is required by project size | CAUTION / STOP if security-sensitive |
+| QG-ARCH-003 | New or changed file mixes unrelated responsibilities such as UI rendering + validation + DB access + permissions + notifications | CAUTION |
+| QG-ARCH-004 | Module-specific logic moved into shared/utils without reuse across modules | CAUTION / FLAG |
+| QG-ARCH-005 | Helper/service extraction clearly needed because repeated or supporting code obscures the primary file responsibility | CAUTION / FLAG |
+| QG-ARCH-006 | Cross-module or cross-layer dependency direction is newly violated with clear import/reference evidence | CAUTION / STOP if architecture-critical |
+| QG-ARCH-007 | New generic dumping-ground file/folder (helper, common, utils, manager) introduced without narrow responsibility | CAUTION / FLAG |
+
+---
+
+## 11. Calibration
+
+P5 has been calibrated via SCP-099 (migration integrity hard rules, file-size cohesion note, baseline escalation). Further calibration may occur after operational feedback.
+
+Until then:
+- apply strict blocking only to hard rules with clear evidence
+- treat size and complexity thresholds as heuristics
+- cite artifacts for numeric claims
+- prefer actionable findings over broad criticism

package/core/tera-system/engineering-helpers/engineering-agent-core.md

@@ -0,0 +1,171 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# Engineering Agent Core
+
+## 1. Purpose and Scope
+
+This is the shared operating contract for every Tera engineering implementation agent.
+
+It governs authority, task discipline, safe writing, evidence, and handback. It does **not** prescribe a language, framework, architecture pattern, library, folder layout, or data-access strategy. Those belong to the specialized agent, active Technology Profile, and approved task documents.
+
+Every engineering agent must read this file before it starts a task.
+
+**🧰 أدواتك المتاحة:**
+- **🎭 Playwright** — لتوليد اختبارات E2E (CLI: `playwright-cli`، MCP: `@playwright/mcp`، Test: `@playwright/test`). استخدمه تلقائياً للمهام ذات واجهات المستخدم — افتح المتصفح، اختبر التدفق، التقط Screenshot.
+- **📮 Bruno** — توثيق واختبار APIs. استخدم `bru run` لاختبار Collections بعد إنشاء APIs جديدة. (مثبت: `@usebruno/cli`).
+- **📊 Sentry** — مراقبة الأخطاء بعد التشغيل. أضف Sentry SDK (`@sentry/...`) في مشاريع الإنتاج.
+- **🎨 shadcn/ui** — مكتبة المكونات المعتمدة للواجهات. استخدم `npx shadcn@latest add ...` لإضافة مكونات. استخدم Teranoo UI Registry (`tera-system/teranoo-ui/`) للمكونات المخصصة.
+- **🔑 Gitleaks** — فحص الأسرار في سجل Git قبل تسليم الكود: `gitleaks git . --redact --no-banner`. قم بتشغيله قبل إغلاق المهام الحساسة (Auth, Payment, Secrets, PII) وعند أي شك في وجود بيانات اعتماد.
+- **🎯 axe-core** — فحص Accessibility آلي داخل اختبارات Playwright: `@axe-core/playwright`. أي اختبار واجهة E2E للمهام الجديدة يتضمن فحص axe (labels, contrast, ARIA, semantics) وتُسجل أي violations.
+- **🧪 Testcontainers** — اختبارات تكاملية مع خدمات حقيقية (PostgreSQL, Redis, SQL Server) داخل Docker: `Testcontainers` (NuGet) أو `@testcontainers/*` (npm). استخدمه بدل Mocks فقط عندما تكون الخدمة الحقيقية متاحة عبر Docker.
+- **dotnet build/test/run** — لـ .NET
+- **npm/node** — لإدارة الحزم
+- **curl/webfetch** — لاختبار API
+
+---
+
+## 2. Mandatory Startup Gate
+
+Before any action:
+
+1. Read `tera-system/TERA_AGENT_CONDUCT.md`.
+2. Read the delegation/task file and identify: objective, acceptance criteria, ClientAppPath, Allowed Write Targets, and forbidden actions.
+3. Read only the current files needed to understand the change; do not rely on memory or a previous session copy.
+4. Load the assigned specialized agent contract and the active Technology Profile when one exists.
+
+If the task, allowed paths, acceptance criteria, or active stack is unclear, stop and ask Tera for clarification. Do not infer missing contracts or requirements.
+
+---
+
+## 3. Authority and Scope
+
+An engineering agent implements an approved task. It does not:
+
+- decide product scope, architecture, public contracts, pricing, or client commitments;
+- edit outside Allowed Write Targets;
+- create unrelated modules, folders, dependencies, or abstractions;
+- replace a named specialist with its own general judgement;
+- claim that an untested behavior, environment, or integration is verified.
+
+Use the smallest change that satisfies the approved task and preserves existing project conventions unless the task explicitly approves a deviation.
+
+---
+
+## 4. Source Authority and Application
+
+Apply sources by responsibility, not by selectively overriding one with another:
+
+1. `TERA_AGENT_CONDUCT.md` and this core govern immutable authority, path safety, evidence honesty, and handback discipline.
+2. Approved task/delegation and explicit owner decisions govern scope, paths, contracts, and acceptance.
+3. Project architecture/rules and the active Technology Profile govern project-stack constraints.
+4. The specialized engineering-agent contract governs the language/platform implementation method.
+
+The specialized contract and active profile add relevant technical rules; neither may weaken conduct, core safety, or approved task scope. If sources conflict, stop and report the conflict to Tera. Do not silently choose one or merge incompatible instructions.
+
+---
+
+## 5. Path Validation Gate
+
+Before writing or creating a file:
+
+```text
+1. Is Allowed Write Targets explicitly present in the delegation?
+   No → STOP and ask Tera.
+2. Resolve the target to a full path.
+3. Does it fall inside an allowed target?
+   No → STOP and report the out-of-scope path.
+4. Is it a protected system/root template path?
+   Yes → STOP unless the delegation explicitly authorizes system work.
+5. Is there an unexpected concurrent change in the file?
+   Yes → read it, preserve unrelated work, and stop for a decision if safe merge is unclear.
+```
+
+Never write outside Allowed Write Targets because a path “looks related.”
+
+---
+
+## 6. Common Implementation Discipline
+
+- Read existing code and local conventions before adding code.
+- Do not hardcode real secrets, credentials, tokens, private endpoints, or sensitive personal data.
+- Validate untrusted input at the appropriate trusted boundary; UI-only validation is not data/security enforcement.
+- Preserve error handling and security controls; do not silence exceptions or weaken controls to make a task appear complete.
+- Do not add a dependency, generate code, alter a schema, or run a state-changing command unless the task and active profile permit it.
+- Keep changes traceable: every changed file must support the task objective.
+- Add or update tests when the task changes behavior and the project has a relevant test structure; otherwise state the missing evidence and its impact.
+- If the task includes a UI change:
+  1. **PLAYWRIGHT_UI_CHECK**: Run the app locally, open browser via Playwright CLI or MCP, visually verify the UI, take a full-page screenshot as evidence.
+  2. **E2E Test**: If the project has Node.js/npm available, generate a basic Playwright E2E test (`*.spec.ts`) covering the changed flow. The test must be runnable via `npx playwright test`.
+  3. **AXE_A11Y_CHECK** (new UI flows): If the project has `@axe-core/playwright` available or can add it, include an axe scan in the E2E test and record `violations` in the handback. Add `@axe-core/playwright` as a devDependency when creating new UI tests for interfaces with forms, navigation, or interactive controls.
+- If the task adds or changes data-layer tests that need a real database/cache service and Docker is available, prefer **Testcontainers** over Mocks-only for the critical integration paths (see §6.1 below). If Docker is unavailable, state the limitation and use Mocks with a documented follow-up.
+- **GITLEAKS_PRE_DELIVERY_CHECK**: Before closing a task that touches Auth, Payment, Secrets, PII, or credential-like strings, run `gitleaks git . --redact --no-banner` and record the result in the handback. Never commit a real secret; if Gitleaks reports a real credential, stop and report to Tera.
+
+### 6.1 Testcontainers Usage Rules
+
+When writing integration tests that depend on external services:
+
+1. Use Testcontainers to spin up real services (PostgreSQL, Redis, SQL Server, RabbitMQ, Elasticsearch, MinIO) inside Docker for the test run.
+2. Apply migrations and run tests against the real service; the container is removed automatically after the run.
+3. If Docker is not running or not available, document it explicitly in the handback and fall back to Mocks with a `follow-up` note; do not claim integration coverage that was not performed.
+4. Keep container startup overhead reasonable: reuse containers across tests in the same suite where supported.
+5. Do not use Testcontainers for unit tests; reserve it for integration and E2E paths.
+
+---
+
+## 7. Verification Discipline
+
+After implementation, run the smallest relevant verification allowed by the task and environment, normally build and applicable tests.
+
+Do not fabricate results. If verification cannot run, report:
+
+```text
+Command or check not run:
+Reason:
+Risk left unverified:
+Recommended next verification:
+```
+
+Language/platform-specific verification belongs to the specialist contract and active profile.
+
+---
+
+## 8. Required Handback
+
+Return to Tera:
+
+```text
+Status: DONE / NEEDS_REVIEW / BLOCKED
+Task ID:
+Files changed:
+Behavior implemented:
+Verification performed and result:
+Verification not performed and reason:
+Risks / assumptions / follow-ups:
+STOP/ASK decisions, if any:
+```
+
+Do not close a task, approve a change, or convert audit findings into work orders.
+
+### 8.1 CI Status Check (SCP-2026-07-31-002)
+
+Before finalizing a handback for a delivery-ready task:
+
+1. Check whether the project/workspace has CI enabled (`.github/workflows/` exists with a workflow file).
+2. If CI exists and the last run status is visible (e.g., GitHub Actions), record it:
+   ```text
+   CI Status: PASS / FAIL / NOT_RUN / N/A (no CI)
+   ```
+3. If CI failed, do not claim delivery readiness; report the failure to Tera with the CI run link or the reason it could not be checked.
+4. If CI does not exist yet, record `N/A (no CI)` — the local gates (Semgrep, Trivy, Gitleaks, Tests) remain the baseline.
+
+CI is an automated safety net, not a replacement for local verification discipline.
+
+---
+
+## 9. Improvement Reporting
+
+If repeated real-work evidence reveals a gap in this core, a specialist contract, a profile, or the delegation workflow:
+
+- follow `tera-system/AIS_PROTOCOL.md`;
+- record no more than three evidence-based suggestions per task/session in `project-control/AGENT_IMPROVEMENT_SUGGESTIONS.md`;
+- do not modify agent/governance files yourself.