@tera-system/core 0.2.1 → 0.2.3

package/core/tera-system/TeraClientPolicy.md

@@ -203,7 +203,7 @@ The default mandatory package is:
 - `10_CLIENT_APPROVAL_RECORD.md`
 - `11_CHANGE_CONTROL.md`
 
-If a file is not applicable to a very small project, Tera must still create an explicit section in `10_CLIENT_APPROVAL_RECORD.md` explaining why it is not applicable and what replaced it.
+If a file is not applicable to a very small project, Tera must still create an explicit section in `10_CLIENT_APPROVAL_RECORD.md` explaining why it is not applicable and what replaced it. Exception: `08_PROTOTYPE_PLAN.md` may not be marked not applicable except with a documented Majed waiver (WAIVED_BY_MAJED) — the prototype is mandatory for all applications (SCP-2026-08-28-001).
 
 ### Approval Gates
 
@@ -214,9 +214,35 @@ If a file is not applicable to a very small project, Tera must still create an e
 | Gate 3: Flow Approval | The client confirms the main user and business flows. |
 | Gate 4: Screen Approval | The client confirms the screen list and screen purposes. |
 | Gate 5: Design Direction Approval | The client confirms visual direction, tone, and references. |
-| Gate 6: Prototype Approval | The client confirms the prototype or prototype plan when applicable. |
+| Gate 6: Prototype Approval | The client confirms the actual prototype (built and reviewed) via a formal approval letter. Mandatory for all applications. Exception: documented Majed waiver (WAIVED_BY_MAJED). |
 | Gate 7: Execution Authorization | The client authorizes moving into implementation. |
 
+### Prototype Mandate (SCP-2026-08-28-001)
+
+```text
+1. Every application — external or internal — requires an approved prototype before
+   real implementation. The only exception is a documented Majed waiver
+   (WAIVED_BY_MAJED) recorded in 10_CLIENT_APPROVAL_RECORD.md with a reason.
+   No agent may override this gate.
+2. The prototype is built by Coding Agents under Tera as the FIRST execution task
+   (TASK-PROTO-*), isolated under project-control/prototypes/ — non-production,
+   deleted or archived after approval. DesignReviewer (ناقد) reviews it before
+   it is shown to Majed and the client (Maker/Checker pattern).
+3. Coverage: all screens listed in 06_SCREEN_MAP.md. Large applications use waves
+   (critical transaction/input screens first); reducing waves is a Majed decision only.
+4. Approval evidence: a formal Prototype Approval Letter (see
+   tera-workshop/client-templates/contractual/PROTOTYPE_APPROVAL_LETTER_TEMPLATE.md)
+   confirming the screens/fields/flows as prototyped, and acknowledging that any
+   later impactful change = priced Change Request on the client's responsibility.
+   The letter is the Gate 6 evidence; without it (or a Majed waiver) the prototype
+   is not approved.
+5. The prototype must trace strictly to the approved baseline
+   (07_SCREENS_AND_UI_STRUCTURE.md) — it validates and surfaces gaps; it does not
+   invent requirements. Objections within approved scope = free design iteration
+   (baseline update via مُهندس when needed). Expansion beyond approved scope =
+   priced Change Request (MR4).
+```
+
 ### Approval Record
 
 `10_CLIENT_APPROVAL_RECORD.md` must document:

package/core/tera-system/TeraPolicyMap.md

@@ -38,7 +38,7 @@ Project files record project-specific decisions.
 | TCEA commercial value discovery (MR6) | `.opencode/agents/tera-client-engagement.md` (A.6.0 MR6) | `.opencode/agents/tera.md` | 6th Master Rule: TCEA must actively discover value-added opportunities — propose as options, not commitments. |
 | TCEA value-added proposals protocol | `tera-system/client-helpers/tera-client-engagement-protocols.md` (A.6.10) | Not applicable | Detailed protocol for commercial proposals: types, rules, template, connection to Future-Proof Discovery. |
 | Solution preparation (phases 1–4) | `.opencode/agents/application-blueprint.md` | `.opencode/agents/tera.md` (reference only) | Owned by مُهندس. Covers blueprint, intake, project decision, preparation planning, delegation, cross-review, baseline, and Engineering Handoff. SCP-2026-07-28-118. |
-| Preparation file catalog | `tera-system/Tera_Project_Preparation_Files.md` | `TERA_PROJECT_DECISION.md` | Comprehensive preparation files **Guide** (catalog + per-file purpose/questions/outputs) owned by مُهندس during preparation. Classified as reference Guide — not split (2026-08-01). |
+| Preparation file catalog | `tera-system/Tera_Project_Preparation_Files.md` + `tera-system/agent-helpers/Tera_Project_Preparation_Files_Conditional.md` | `TERA_PROJECT_DECISION.md` | Main guide/index plus on-demand companion for conditional and supporting files. Owned by مُهندس during preparation. |
 | Project decision template | `tera-system/TERA_PROJECT_DECISION.md` + `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §1 | Not applicable | Owned by مُهندس. 13-section structure. |
 | 7-phase Tera workflow | `.opencode/agents/tera.md` §11 (phases 5–7) + `.opencode/agents/application-blueprint.md` (phases 1–4) | Runtime files as referenced | Phases 1–4: مُهندس. Phases 5–7: Tera. SCP-2026-07-28-118. |
 | Phase 3 preparation planning output | `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §2 | `.opencode/agents/application-blueprint.md` | Produces `PREPARATION_PLAN.md`; owned by مُهندس. |
@@ -49,7 +49,7 @@ Project files record project-specific decisions.
 | Phase 5 execution planning outputs | `tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md` Sections 29-31 | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md`, `TeraPreExecutionGate.md` | Produces `PROJECT_MASTER_PLAN.md`, `PROJECT_DETAILED_EXECUTION_PLAN.md`, and `EXECUTION_BATCH_PLAN.md`. Split notice INS-02: Sections 29-31 moved to DELIVERY file. |
 | Phase 6 post-execution review template | `tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md` Section 32 | `TASK_TEMPLATE.md`, `TeraPreExecutionGate.md`, `TERA_RUNTIME_CHECKLISTS.md` | Used inside `TASK-COD-*` before final acceptance or closure. Note: `TASK_TEMPLATE.md` lives at `project-control/tasks/TASK_TEMPLATE.md` (clarified INS-07, 2026-08-01). Split notice INS-02: Section 32 moved to DELIVERY file. |
 | Phase 7 delivery, handover, and closure | `.opencode/agents/tera.md` Section 5 + `TERA_RUNTIME_TEMPLATES_DELIVERY.md` Section 35 | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md`, `TERA_RUNTIME_PROTOCOLS.md` | Project closure is separate from last TASK-COD closure. Phase 7 does not execute code. Split notice INS-02: Section 34 moved to DELIVERY file. |
-| Sub-agent registry (core) | `tera-system/TeraSubAgents.md` | `.opencode/agents/tera.md` | Core agents (Engineering, QA, Auditor, Software Designer) — 769 lines 🟢 |
+| Sub-agent registry (core) | `tera-system/TeraSubAgents.md` | `.opencode/agents/tera.md` | Core agents (Engineering, QA, Auditor, Software Designer, DesignReviewer) — 904 lines 🟡 |
 | Sub-agent registry (helpers) | `tera-system/TeraHelperAgents.md` | `.opencode/agents/tera.md` | Helper agents (Security, DevOps, Domain, ERP, etc.) — 964 lines 🟢 — split from TeraSubAgents.md via SCP-2026-07-26 |
 | Agent generation template | `tera-system/AGENT_GENERATION_TEMPLATE.md` | `TERA_RUNTIME_PROTOCOLS_CORE.md` | Draft agents use this source. |
 | Pre/Post execution gates | `tera-system/TeraPreExecutionGate.md` | `.opencode/agents/tera.md`, `TERA_RUNTIME_PROTOCOLS_CORE.md` | Gate details stay in the policy file. |
@@ -61,7 +61,8 @@ Project files record project-specific decisions.
 | Runtime checklists | `tera-system/runtime/TERA_RUNTIME_CHECKLISTS.md` | `.opencode/agents/tera.md` | Checklists stay outside runtime. |
 | MVP classification | `tera-system/runtime/MVP_DEFINITION_PROTOCOL.md` | `.opencode/agents/tera.md` | Runtime references when to load it. |
 | Technology profiles | `tera-system/profiles/` | `.opencode/agents/tera.md` | Stack-specific rules stay in profiles. |
-| Design governance layer | `tera-system/design-system/` | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md`, `TERA_RUNTIME_PROTOCOLS_CORE.md` | Governs Design Source Decision, DESIGN.md integration, internal kits, design tokens, component rules, and UI Acceptance Gate. |
+| Design governance layer | `tera-system/design-system/` | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md`, `TERA_RUNTIME_PROTOCOLS_CORE.md` | Governs Design Source Decision, DESIGN.md integration, internal kits, design tokens, component rules, and UI Acceptance Gate. DesignReviewer (ناقد) = Tera-managed review sub-agent (SCP-2026-08-28-001) with three shields (neutrality / direct escalation / dual invocation). |
+| Prototype mandate | `tera-system/TeraClientPolicy.md` (Prototype Mandate — SCP-2026-08-28-001) | `TERA_RUNTIME_TEMPLATES.md` (08_PROTOTYPE_PLAN.md), `TERA_RUNTIME_PROTOCOLS_CLIENT.md`, `TeraPreExecutionGate.md` (#23) | Gate 6 mandatory for all applications; waiver = documented `WAIVED_BY_MAJED` only. Builder: Coding Agents under Tera (TASK-PROTO-*); reviewer: DesignReviewer (ناقد); evidence: formal Prototype Approval Letter. |
 | Monitor audit framework | `.opencode/agents/monitor.md` | `ENGINEERING_AGENT_RESPONSIBILITIES.md` | Governs the 7 immutable audit rules, reference hierarchy, plan rejection authority, and cumulative audit for plan-compliance checking. |
 | Auditor audit framework | `.opencode/agents/auditor.md` | `ENGINEERING_AGENT_RESPONSIBILITIES.md` | Governs Auditor as a Tera-managed quality gate sub-agent, including diff-first scope, evidence model, QUAUD reporting, and authorized invocation by Tera/Monitor. |
 | Quality gate thresholds | `tera-system/engineering-governance/QUALITY_GATE_THRESHOLDS.md` | `.opencode/agents/auditor.md`, `.opencode/agents/tera.md` | Compact reference for Auditor rule classes, evidence requirements, P1/P2 checks, and default heuristics. |
@@ -104,7 +105,8 @@ Project files record project-specific decisions.
 | Business Transformation Consultant (BTCA) | `.opencode/agents/tera-business-transformation-consultant.md` | `tera-system/consulting-helpers/BTCA_METHODOLOGY_FRAMEWORK.md`, `BTCA_REPORT_TEMPLATES.md` | عميل مستقل للاستشارات الإدارية والتنظيمية غير البرمجية — Track C. SCP-2026-07-29-002. |
 | BTCA — Methodology Framework | `tera-system/consulting-helpers/BTCA_METHODOLOGY_FRAMEWORK.md` | `.opencode/agents/tera-business-transformation-consultant.md` | إطار المنهجية: تصنيف الأدلة الخماسي، مراحل العمل، دليل المقابلات، هيكل التقرير النهائي. |
 | BTCA — Report Templates | `tera-system/consulting-helpers/BTCA_REPORT_TEMPLATES.md` | `.opencode/agents/tera-business-transformation-consultant.md` | قوالب التقارير العشرة الأساسية + التقرير التنفيذي. |
-| Tera distribution (versioned) | `tera-system/TERA_DISTRIBUTION_POLICY.md` | `.tera/lock.json` في مستودعات العملاء | توزيع Tera المُروّس على مستودعات العملاء: استمداد من المستودع الأصلي (`tera-fetch.ps1` + RepositoryUrl)، إصدارات (Tag+SHA)، عقد ملكية، أدوات `tera-workshop/tools/`. SCP-2026-08-15-009. |
+| Tera distribution (versioned) | `tera-system/TERA_DISTRIBUTION_POLICY.md` | `.tera/lock.json` في مستودعات العملاء | توزيع Tera المُروّس على مستودعات العملاء: استمداد من المستودع الأصلي (`tera-fetch.ps1` + RepositoryUrl)، إصدارات (Tag+SHA)، عقد ملكية، أدوات `tera-workshop/tools/`. SCP-2026-08-15-009. |
+| Tera product standards — Maintenance | `tera-system/product-standards/maintenance-apps/STANDARD_DEFINITION.md` + `BEST_PRACTICES_DOMAIN.md` | Not applicable | Active reusable product standards for Maintenance/FSM/WOM; content remains in the standards files. |
 
 ## 4. Duplication Policy
 

package/core/tera-system/TeraPreExecutionGate.md

@@ -219,6 +219,7 @@ BLOCKED
 | 20 | هل يوجد مسار تراجع آمن إذا فشل التنفيذ؟ | Yes |
 | 21 | إذا كانت المهمة UI/Frontend، هل يوجد Design Source Decision و`28_UI_UX_GUIDELINES.md` عند الحاجة؟ | Yes / N/A |
 | 22 | إذا كانت المهمة UI/Frontend، هل ترتبط بـ `UI_ACCEPTANCE_GATE.md` وتتضمن UI Source / UI Rules / UI Acceptance / Design Gap Handling؟ | Yes / N/A |
+| 23 | هل تم اعتماد البروتوتايب (Gate 6 — خطاب رسمي) أو توثيق `WAIVED_BY_MAJED` قبل أي مهمة تنفيذ فعلية؟ (لا ينطبق على مهام البروتوتايب نفسها `TASK-PROTO-*` — فهي Spike معتمد من Majed) | Yes / N/A (مشروع بلا واجهات) |
 
 إذا فشل أي بند، يجب على Tera تصحيح المهمة قبل عرضها.
 

package/core/tera-system/TeraProjectIntakePolicy.md

@@ -125,7 +125,7 @@ For external client projects, also ask the shortest useful client questions:
 - What language should client documents use? Default is Arabic.
 - Does the client have a logo, colors, references, or examples they like?
 - Are there examples the client dislikes?
-- Does the client need a proposal, prototype, or design approval before implementation?
+- Does the client need a proposal, prototype, or design approval before implementation? (الافتراضي: البروتوتايب إلزامي لجميع التطبيقات — SCP-2026-08-28-001 — إلا بتجاوز Majed موثق `WAIVED_BY_MAJED`)
 
 ## 8. When Tera Can Proceed
 
@@ -142,7 +142,7 @@ For external client projects, Tera may proceed only to client approval preparati
 - the client application folder under `clients/` is identified.
 - Tera has enough information to produce a client-facing approval package.
 
-Tera may not proceed to implementation until `tera-system/TeraClientPolicy.md` (Section 7: Client Approval Package) is satisfied.
+Tera may not proceed to implementation until `tera-system/TeraClientPolicy.md` (Section 7: Client Approval Package) is satisfied — including Gate 6 Prototype Approval (formal letter) or a documented `WAIVED_BY_MAJED` (SCP-2026-08-28-001).
 
 ## 9. Relationship with 00_PROJECT_INPUTS.md
 

package/core/tera-system/TeraSubAgents.md

@@ -789,8 +789,58 @@ project-control/audit-reports/QUAUD-[TASK-ID]-YYYY-MM-DD-NNN.md
 - لا يحتوي أسراراً حقيقية أو بيانات غير منقحة.
 - يستخدم STOP / CAUTION / FLAG دون تحويل heuristics إلى blockers تلقائياً.
 
----
-
+---
+
+## 5.7.2 DesignReviewer — ناقد (SCP-2026-08-28-001)
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Design Reviewer Agent |
+| المعرّف | `DESIGN_REVIEWER` |
+| الفئة | أساسي / مراجعة بصرية (Tera-managed review sub-agent) |
+| ملف العميل | `.opencode/agents/design-reviewer.md` |
+| الدور | مراجعة البروتوتايب (TASK-PROTO-*) والواجهات المنفذة مقابل مصدر التصميم المعتمد — حكم مستقل |
+
+### متى يستدعيه Tera؟
+
+- بعد بناء البروتوتايب (`TASK-PROTO-*`) — قبل عرضه على Majed/الزبون (نمط Maker/Checker).
+- عند الحاجة لمراجعة بصرية للواجهات المنفذة أثناء التنفيذ (قبل القبول).
+
+### متى يستدعيه Majed مباشرة؟
+
+- في أي وقت (درع الاستدعاء المزدوج) — لا احتكار من Tera.
+
+### الدروع الثلاثة (إلزامية)
+
+- 🛡️ **درع الحياد**: قاعدة Reviewer Invocation Neutrality — ممنوع تلقين النتائج المتوقعة.
+- 🛡️ **درع التصعيد**: يرفع نتائجه إلى Majed مباشرة دون تحرير من Tera.
+- 🛡️ **درع الاستدعاء**: Majed يستدعيه مباشرة في أي وقت.
+
+### يقرأ
+
+```text
+project-control/prototypes/ (البروتوتايب المبني)
+project-preparation/07_SCREENS_AND_UI_STRUCTURE.md
+project-preparation/28_UI_UX_GUIDELINES.md
+project-preparation/design-source/ عند وجوده
+tera-system/design-system/DESIGN_REVIEW_STANDARDS.md (يُقرأ قبل كل مراجعة)
+```
+
+### ينتج
+
+```text
+تقرير مراجعة تصميم/بروتوتايب مستقل إلى Majed (PASS / REVISION / BLOCKED)
+```
+
+### حدوده
+
+- لا يبني البروتوتايب — البناء حصراً Coding Agents تحت Tera.
+- لا يكتب أو يعدّل كود التطبيق ولا التصميم.
+- لا يقبل المهمة ولا يغلقها — يوصي فقط.
+- لا يحل محل Monitor (الرقابة على الخطط) ولا Auditor (الجودة الهندسية).
+
+---
+
 ## 5.8 DocumentationHandoverAgent
 
 | البند | القيمة |

package/core/tera-system/TeraSystemMaintenanceChecklist.md

@@ -15,6 +15,7 @@ Check:
 - Is this a new rule, a clarification, or a runtime summary?
 - Can an existing file be updated instead of creating a new file?
 - Will this affect `.opencode/agents/tera.md` runtime behavior?
+- Will agent roles or relationships documented in `book/` change? If yes, plan a `book/` sync pass in the same batch (SCP-2026-08-28-002).
 - Does this require updating `TeraPolicyMap.md` or `TeraArchitectureMap.md`?
 
 ## 3. During Editing
@@ -75,6 +76,7 @@ When the maintenance change is complete, summarize:
 
 - source files changed
 - runtime sync needed: yes / no
+- book/ sync needed (agent roles/relationships changed): yes / no / n/a
 - duplicate rules removed or accepted
 - validation performed
 - remaining risks