@tera-system/core 0.1.0

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

@@ -0,0 +1,210 @@
+# ENGINEERING_AGENT_RESPONSIBILITIES.md
+
+## Engineering Governance Responsibilities by Agent
+
+| Metadata | |
+|---|---|
+| **Status** | Active responsibility map |
+| **Source** | `ENGINEERING_BEST_PRACTICES.md` |
+| **Last Updated** | 2026-07-04 |
+
+---
+
+## 1. Purpose
+
+This file defines how engineering governance is distributed across Tera and its agents.
+
+No single agent reviews everything. Each agent receives the part of the engineering ideals related to its role.
+
+---
+
+## 2. Tera Agent
+
+Tera must:
+
+- decide the project engineering governance level: Compact / Standard / Full;
+- ensure preparation and execution plans include maintainability constraints;
+- run or reference the Engineering Governance Gate before implementation tasks when applicable;
+- prevent scope expansion and over-engineering;
+- decide when Auditor, Monitor, QA, Security, or other agents are needed;
+- record engineering deviations as issues, decisions, or task review notes.
+
+---
+
+## 3. SolutionArchitectureAgent
+
+Must focus on:
+
+- module boundaries;
+- layer selection appropriate to project size;
+- service/use-case/domain separation where justified;
+- avoiding enterprise architecture in small projects;
+- documenting architecture decisions and tradeoffs.
+
+---
+
+## 4. EngineeringAgent
+
+Must implement according to:
+
+- approved module/folder structure;
+- single responsibility;
+- no UI/business logic mixing when avoidable;
+- no random `shared/` or `utils` dumping;
+- active Technology Profile;
+- task Allowed Write Targets;
+- tests when required by the task or important business logic.
+
+Must escalate when the existing structure conflicts with the task or would require architectural deviation.
+
+---
+
+## 5. Auditor
+
+Auditor (مُدقق) is defined in its own file: `.opencode/agents/auditor.md`.
+
+This section only documents the engineering-adjacent boundary.
+
+### 5.1 Core methodology
+
+Auditor is a Tera-managed quality gate sub-agent. It follows the diff-first, evidence-based methodology defined in `.opencode/agents/auditor.md`:
+
+1. Confirm authorized invocation by Tera or Monitor.
+2. Review changed code/files first, then directly affected units.
+3. Verify documentation, Handback, Compliance Record, and available evidence artifacts.
+4. Apply P1/P2 quality checks using `QUALITY_GATE_THRESHOLDS.md`.
+5. Classify findings as STOP / CAUTION / FLAG / BASELINE_DEBT.
+6. Produce a QUAUD report and return it to the orchestrator.
+
+### 5.2 Engineering review scope
+
+When code or implementation output is in scope, Auditor must review:
+
+- module and file structure;
+- oversized or multi-responsibility files;
+- UI/business logic separation;
+- shared/utils misuse;
+- validation, permissions, error handling, and tests relevant to the task;
+- whether deviations are documented.
+
+Auditor must not focus only on superficial formatting or minor documentation issues.
+
+### 5.3 Audit reports
+
+Auditor writes formal reports only under `project-control/audit-reports/` when that path is included in Allowed Write Targets, and returns a summary to the invoking orchestrator.
+
+### 5.4 Uncertainty protocol
+
+When documentation is missing, sources conflict, or the audit scope is unclear, Auditor must:
+1. Ask the orchestrator for the missing evidence or allowed artifact.
+2. Use external verification only when allowed and relevant.
+3. Return `DEFERRED` or `NEEDS_FIX` when evidence is insufficient.
+4. Never guess or fabricate audit findings.
+
+### 5.5 Authority
+
+Auditor remains advisory and cannot approve, close, commit, or implement. Findings become executable only when Tera, Monitor, ProjectControlAgent, or Majed converts them into tasks/issues.
+
+---
+
+## 6. Monitor
+
+Monitor (رقيب) is defined in its own file: `.opencode/agents/monitor.md`.
+
+This section only documents the engineering-adjacent boundary:
+
+Monitor is a plan-compliance auditor, not a code quality reviewer. Monitor audit framework is governed by **7 immutable rules** (defined in `.opencode/agents/monitor.md` §5):
+
+1. **Plan match** — task exists in batch and master plans.
+2. **Dependencies** — fulfilled before task start.
+3. **Engineering Gate** — ENGINEERING_GOVERNANCE_GATE.md referenced when tasks touch Code/API/DB/UI/Tests.
+4. **Compliance Record** — all 8 items complete in task file.
+5. **Handback vs Git diff** — cross-check using `git diff --name-only`.
+6. **Scope creep** — changed files not linked to any task in current plan.
+7. **Architectural drift** — unplanned modules, APIs, DB, UI not in Master Plan.
+
+Monitor has **Plan Rejection Authority** (`.opencode/agents/monitor.md` §6): may reject or request review of a plan when it is missing, ambiguous, contains unlinked tasks, lacks compliance records, or skips engineering governance gates. Final decision rests with Majed.
+
+Monitor must not become a general code auditor; detailed code quality review belongs to Auditor and QA.
+
+Monitor keeps a working state in `MONITOR_STATE.md` (not a source of truth; no priority over Git or governing records — SCP-2026-08-16-004).
+Monitor findings use `BLOCKING / MATERIAL / NOTE` only — never Auditor's `STOP/CAUTION/FLAG/BASELINE_DEBT`. Monitor never executes fixes.
+
+---
+
+## 7. qa-agent
+
+QA must focus on:
+
+- testability of important business logic;
+- acceptance criteria coverage;
+- validation and permission behavior from user/API perspective;
+- workflow/status transition correctness;
+- whether missing tests create acceptance risk.
+
+QA does not replace SecurityAgent for specialized security review.
+
+---
+
+## 8. SecurityAgent
+
+SecurityAgent must focus on:
+
+- permissions enforced beyond UI;
+- auth/session/JWT/cookie/middleware safety;
+- secret handling and redaction;
+- sensitive config;
+- server-side validation for security-sensitive inputs;
+- audit log expectations for sensitive operations.
+
+---
+
+## 9. ProjectControlAgent
+
+ProjectControlAgent must ensure:
+
+- engineering deviations are recorded;
+- task review findings are linked to `TASK-ID`;
+- issues/gaps have severity, status, and recommended action;
+- decisions are recorded when architecture or maintainability tradeoffs are accepted;
+- project state reflects significant governance changes.
+
+---
+
+## 10. PerformanceAgent
+
+PerformanceAgent must focus on:
+
+- pagination and bounded queries;
+- indexes for important access paths;
+- heavy reports or dashboards;
+- unnecessary data loading;
+- performance risks without pushing premature optimization.
+
+---
+
+## 11. DesignReviewer
+
+DesignReviewer (ناقد) is defined in its own file: `.opencode/agents/design-reviewer.md`.
+DesignReviewer review standards reference: `tera-system/design-system/DESIGN_REVIEW_STANDARDS.md`.
+
+This section only documents the engineering-adjacent boundary:
+
+DesignReviewer remains visual/design focused. It may report engineering-adjacent issues only when they affect UI consistency or maintainability, such as:
+
+- duplicated visual components;
+- inconsistent component variants;
+- layout patterns not following `28_UI_UX_GUIDELINES.md`;
+- UI implementation that makes future visual changes unnecessarily hard.
+
+DesignReviewer may build static HTML/CSS prototypes from design sources for visual review when Majed requests. Prototypes are for review only, not production code. Temporary files stored in `project-control/prototypes/` and deleted after approval.
+
+DesignReviewer must not become a general code architecture auditor.
+
+---
+
+## 12. Domain Agents
+
+Domain agents may recommend workflow, status, approval, or domain-rule structure, but they must not turn external references into implementation scope automatically.
+
+Engineering adoption remains Tera's decision.

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

@@ -0,0 +1,468 @@
+# ENGINEERING_BEST_PRACTICES.md
+
+## Tera Engineering Governance Layer — Best Practices
+
+| Metadata | |
+|---|---|
+| **Status** | Active system policy |
+| **Source** | Derived from Majed's `temp/Note01.md` / `temp/Developer Best Practice.md` and normalized for Tera governance |
+| **Scope** | All future Tera-managed applications, adjusted by project size and technology profile |
+| **Last Updated** | 2026-07-01 |
+
+---
+
+## 1. Purpose
+
+This file defines Tera's engineering ideals for maintainable application code, architecture, and delivery.
+
+The goal is to prevent applications from becoming:
+
+- oversized and hard to change;
+- randomly structured;
+- tightly coupled;
+- UI-heavy with hidden business logic;
+- weak in validation, permissions, testing, or error handling;
+- dependent on AI-generated code without governance.
+
+This policy is not a license to over-engineer. It must be applied proportionally to the project size, domain risk, approved scope, and active Technology Profile.
+
+---
+
+## 2. Core Principle
+
+```text
+Every application must be structured for safe change.
+```
+
+Safe change means:
+
+- modules are clear;
+- responsibilities are separated;
+- files remain reviewable;
+- business rules are not hidden in UI;
+- validation, permissions, errors, and tests are consistent;
+- database and API changes are traceable;
+- AI agents cannot expand or degrade architecture silently.
+
+---
+
+## 3. Project Size Levels
+
+| Level | Use When | Engineering Governance Depth |
+|---|---|---|
+| **Compact** | small CRUD / prototype / internal utility | Basic modules, file-size awareness, no random shared/utils, minimal tests for important rules |
+| **Standard** | typical web app with dashboard, API, auth, database | Feature/module structure, service/use-case separation where useful, validation/error/security rules, task-level review |
+| **Full** | ERP, SaaS, multi-role, workflow-heavy, high data/security risk | Layered architecture, domain/application/infrastructure separation, audit logs, integration boundaries, stronger testing and review |
+
+Tera decides the level during project preparation and records it in the active application workspace, normally in `project-preparation/08_TECHNICAL_ARCHITECTURE.md` or a project-specific engineering standards file.
+
+---
+
+## 4. Structure by Responsibility
+
+Prefer module/feature-oriented structure over random flat folders.
+
+Recommended conceptual structure:
+
+```text
+src/
+  core/
+    config/
+    errors/
+    logger/
+    security/
+    database/
+  shared/
+    components/
+    utils/
+    validators/
+    types/
+    constants/
+  modules/
+    [module-name]/
+      ui/
+      application/
+      domain/
+      infrastructure/
+      tests/
+```
+
+Rules:
+
+- Every important business feature belongs to an explicit module.
+- `shared/` contains only code used by more than one module.
+- Module-specific rules must not be moved into `shared/` merely for convenience.
+- Technology-specific folder naming may differ, but responsibility boundaries must remain clear.
+
+---
+
+## 5. File Size and Responsibility
+
+Any file approaching roughly `300–400` lines should be reviewed for responsibility creep.
+
+Large files are not automatically forbidden, but they are suspicious when they combine:
+
+- data fetching;
+- validation;
+- error handling;
+- UI rendering;
+- permissions;
+- formatting;
+- exports;
+- notifications;
+- database operations.
+
+Rule:
+
+```text
+If a file cannot state its responsibility in one sentence, it must be reviewed.
+```
+
+---
+
+## 6. Single Responsibility
+
+Each file, function, component, class, service, or use case should have one primary reason to change.
+
+Bad signal:
+
+```text
+createInvoiceAndValidateCustomerAndUpdateStockAndSendEmail()
+```
+
+Better pattern:
+
+```text
+validateCustomer()
+createInvoice()
+reserveStock()
+sendInvoiceEmail()
+```
+
+An application service or use case may coordinate multiple operations, but should not hide every rule inside one large function.
+
+---
+
+## 7. UI and Business Logic Separation
+
+UI receives input and displays output. It must not become the owner of business rules.
+
+Business logic belongs in one of these areas according to stack and project size:
+
+```text
+application/
+domain/
+services/
+use-cases/
+rules/
+validators/
+repositories/
+```
+
+For example, invoice tax calculation, stock reservation, approval rules, customer credit checks, and permission checks must not be buried inside page components.
+
+---
+
+## 8. DRY With Judgment
+
+Do not extract every small duplicate too early.
+
+| Repetition | Decision |
+|---:|---|
+| once | leave it |
+| twice | watch it |
+| three times | usually extract |
+| more than three | extract unless there is a clear reason not to |
+
+Good shared candidates:
+
+- date/currency formatting;
+- common validation;
+- API response helpers;
+- pagination;
+- current-user helpers;
+- permission helpers;
+- logging;
+- upload/export utilities.
+
+Forbidden pattern:
+
+```text
+shared/utils/ becomes a dumping ground.
+```
+
+---
+
+## 9. Naming Conventions
+
+Names must express purpose clearly. Generic or vague names are not acceptable.
+
+Avoid:
+
+```text
+helper
+common
+manager
+data
+process
+handle
+temp
+```
+
+Guidelines:
+
+- Functions/methods use verbs: `calculateTotal`, `validateInput`, `sendInvoiceEmail`.
+- Classes, components, and variables use nouns: `InvoiceService`, `userList`, `PaymentGateway`.
+- Constants use UPPER_SNAKE_CASE: `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE`.
+- Use one consistent style per project (camelCase / PascalCase / snake_case) according to the language.
+- File names should match their primary export or responsibility.
+
+---
+
+## 10. Validation
+
+Validation must not exist only in UI.
+
+Rules:
+
+- UI validation improves user experience.
+- Backend/API/service validation protects the system.
+- Common validators belong in shared validation only when genuinely shared.
+- Module-specific validation stays inside the module.
+- Database constraints are for data integrity; do not move business validation into database constraints unless explicitly approved.
+
+---
+
+## 11. Error Handling
+
+Applications must use consistent error handling instead of ad-hoc messages everywhere.
+
+Recommended concepts:
+
+```text
+core/errors/
+  app-error
+  validation-error
+  authorization-error
+  not-found-error
+  error-handler
+```
+
+User-facing errors should be consistent and should not expose internal technical details.
+
+---
+
+## 12. Permissions and Security Enforcement
+
+Do not rely on hiding UI buttons as security.
+
+Permissions must be enforced where relevant:
+
+- frontend for UX;
+- backend/API/server actions for actual enforcement;
+- service/domain layer where business-sensitive rules require it;
+- database policies only when explicitly approved for the stack and deployment model.
+
+Examples:
+
+```text
+canApproveInvoice(user, invoice)
+canDeleteCustomer(user, customer)
+canViewCost(user)
+```
+
+---
+
+## 13. Configuration and Secrets
+
+Configuration must be centralized and environment-aware.
+
+Rules:
+
+- Do not scatter URLs, sizes, currencies, or flags across the codebase.
+- Real secrets must never be written into source code, project-control records, task files, logs, handbacks, or fallback config values.
+- Use `.env`, environment variables, or approved local secret storage only.
+
+---
+
+## 14. Logging and Audit
+
+Do not log everything, but important actions must be traceable.
+
+Relevant events include:
+
+- failed login attempts;
+- deletes;
+- approvals;
+- permission changes;
+- sensitive business operations;
+- API errors;
+- integration failures;
+- system exceptions.
+
+For ERP and administration-heavy systems, Audit Log is often essential.
+
+---
+
+## 15. Database Design and Migrations
+
+Database design must be traceable and consistent.
+
+Rules:
+
+- names are clear and consistent;
+- relations use explicit IDs / foreign keys where supported;
+- indexes exist for important search/filter paths;
+- status values are explicit enums or reference records;
+- created/updated metadata exists when useful;
+- soft delete is considered for sensitive administrative data;
+- schema changes use migrations or the approved stack-specific equivalent;
+- no manual production database changes without trace.
+
+---
+
+## 16. API Design
+
+APIs should be predictable and consistent.
+
+Rules:
+
+- endpoint naming is stable;
+- responses have a consistent shape;
+- errors have a consistent format;
+- pagination/filtering/sorting are explicit when needed;
+- versioning is used only when needed;
+- API changes must not silently break planned consumers.
+
+---
+
+## 17. External Integration
+
+When integrating with external services, the system must remain resilient.
+
+Requirements:
+
+- Define explicit timeouts for every external call.
+- Implement limited retry with backoff for transient failures.
+- Handle service outages gracefully: fail with a clear user message instead of crashing.
+- Use Circuit Breaker or equivalent pattern when the external service is critical and failure-prone.
+- Never rely on external service availability without fallback or clear user feedback.
+
+---
+
+## 18. Idempotency and Concurrency
+
+Operations that create side effects (payments, invoices, stock deductions, order confirmations) must be safe to retry.
+
+Design principles:
+
+- Use idempotency keys or request IDs for sensitive write operations.
+- Handle race conditions on shared records using optimistic locking, transactions, or explicit locks.
+- Prevent double processing when the same request arrives more than once.
+
+---
+
+## 19. Testing
+
+Testing must focus on important risk, not test-count vanity.
+
+Default priorities:
+
+- Unit tests for business rules and calculations.
+- Integration/API tests for workflows and endpoints.
+- UI/E2E tests only where they provide real confidence and cost is justified.
+
+Examples that often need tests:
+
+- permissions;
+- approvals/status transitions;
+- invoice/tax/stock calculations;
+- validation rules;
+- deletion prevention;
+- negative quantity prevention;
+- critical API behavior.
+
+---
+
+## 20. Documentation and Decisions
+
+Projects do not need bloated documentation, but they need governing documentation.
+
+Recommended project-level documents when justified:
+
+```text
+ARCHITECTURE.md
+CODING_STANDARDS.md
+DATABASE_GUIDELINES.md
+API_GUIDELINES.md
+TESTING_GUIDELINES.md
+SECURITY_GUIDELINES.md
+DECISIONS.md
+CHANGELOG.md
+```
+
+Within Tera-managed projects, these may be represented by project-preparation and project-control files instead of literal docs, unless the application needs standalone engineering docs.
+
+---
+
+## 21. Git and CI/CD
+
+Rules:
+
+- commits should be small and understandable;
+- one commit should not mix unrelated topics;
+- never commit secrets or local temporary files;
+- at minimum, important projects should support lint/test/build checks before release;
+- CI/CD complexity must match project size.
+
+---
+
+## 22. Performance
+
+Avoid premature optimization, but prevent obvious structural performance mistakes.
+
+Watch for:
+
+- screens loading thousands of records without pagination;
+- missing indexes on common filters;
+- heavy reports without bounded queries;
+- unnecessary data fetching;
+- unoptimized images;
+- expensive operations hidden in UI rendering.
+
+---
+
+## 23. AI Governance
+
+AI-generated work must be constrained by official project files and task scope.
+
+Agents must:
+
+1. understand the approved structure before changing code;
+2. not create duplicate files or folders;
+3. not edit outside the task scope;
+4. not break APIs silently;
+5. not change database structure without a schema/migration task;
+6. add tests when important logic changes;
+7. update or request documentation updates when behavior changes;
+8. report exactly what files were changed;
+9. explain the purpose and impact of each modified file;
+10. record important decisions when the task introduces architectural or behavioral changes;
+11. identify and communicate risks before executing potentially destructive operations (deletions, bulk changes, permission changes, or data migrations).
+
+---
+
+## 24. The Twelve Non-Negotiables
+
+1. Use clear modules.
+2. Separate business logic from UI.
+3. Prevent oversized files.
+4. Extract shared code carefully, not blindly.
+5. Test important business logic.
+6. Enforce permissions beyond the frontend.
+7. Use consistent error handling and logging.
+8. Record important architecture decisions.
+9. Use migrations or traceable database changes.
+10. Govern AI-generated code with task scope, gates, and review.
+11. Protect secrets: never store passwords, tokens, API keys, or credentials in source code, task files, logs, or handbacks.
+12. Do not break existing API contracts without justification and documented migration.