@tera-system/core 0.1.0

package/core/tera-system/TeraPolicyMap.md

@@ -0,0 +1,131 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# Tera Policy Map
+
+## 1. Purpose
+
+This file maps each major Tera operating topic to its official source of truth.
+
+It prevents rule duplication, unclear authority, and runtime bloat as the system grows.
+
+## 2. Rule
+
+```text
+Policies define rules.
+Runtime files summarize operational triggers.
+Guides explain usage.
+Project files record project-specific decisions.
+```
+
+## 3. Source Of Truth Map
+
+| Topic | Source of truth | Runtime summary allowed in | Notes |
+|---|---|---|---|
+| Tera identity and authority | `.opencode/agents/tera.md` | `.opencode/agents/tera.md` | Runtime must stay compact. |
+| Owner strategic advisory | `.opencode/agents/tera-strategic-advisor.md` | Not applicable | Independent advisor for Majed only. Advice is not approval or execution authorization. |
+| Core agent conduct gate | `tera-system/TERA_AGENT_CONDUCT.md` | `.opencode/agents/*.md` | Short runtime reference only. Do not duplicate the conduct rules in each agent file. |
+| Runtime authority order | `.opencode/agents/tera.md` | Not applicable | Active runtime wins until conflict is corrected. |
+| Operating model overview | `.opencode/agents/tera.md` (Section 36) | Not applicable | Merged from Tera Operating Model.md (now deprecated). |
+| System architecture | `tera-system/TeraArchitectureMap.md` | `.opencode/agents/tera.md` | Runtime should only link or summarize. |
+| Project intake | `tera-system/TeraProjectIntakePolicy.md` | `.opencode/agents/application-blueprint.md`, `TERA_SOLUTION_PREPARATION_PROTOCOL.md` | Owned by مُهندس (SCP-2026-07-28-118). Do not duplicate full intake rules elsewhere. |
+| Application question bank | `tera-system/TeraApplicationQuestionBank.md` | `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 18) | Reference bank of categorized questions for Client Discovery + Smart Interview. Includes assumption handling rules. |
+| Client discovery + smart interview | `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 18) | `.opencode/agents/tera.md` | Two-stage intake: open conversation → structured questioning if needed. |
+| Domain intelligence + research | `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 12) | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md` | Covers real-time search during discovery, on-demand research, and the No-Guessing Rule. |
+| Production ERP specialist knowledge | `.opencode/agents/production-erp-expert.md` + `tera-system/knowledge-base/manufacturing/00_INDEX.md` | `TeraSubAgents.md`, `AGENT_ACTIVATION_MATRIX.md` | Agent contract governs behavior; KB index governs readiness/status of local manufacturing knowledge files. |
+| Client policy (unified) | `tera-system/TeraClientPolicy.md` | `.opencode/agents/tera.md`, `TERA_RUNTIME_PROTOCOLS_CORE.md`, `TERA_RUNTIME_TEMPLATES.md` | Merged from 4 separate client files (now deprecated). Covers engagement, approval, change control, and facing content. |
+| TCEA discovery coverage framework | `.opencode/agents/tera-client-engagement.md` | `.opencode/agents/tera.md` | Governs the mandatory 13-domain discovery framework, completeness matrix, Discovery Coverage Gate, Quotation Readiness Gate, and Tera Handoff Readiness Gate for external client work. |
+| TCEA discovery domains (canonical) | `tera-system/client-helpers/tera-client-engagement-discovery-domains.md` | Not applicable | Canonical source for the 13 domains numbering, naming, aliases, coverage, and blocking rules. All other files reference this source. |
+| 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). |
+| 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 مُهندس. |
+| Phase 4 agent delegation output | `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §3 | `.opencode/agents/application-blueprint.md` | Produces `AGENT_DELEGATION_PLAN.md`; owned by مُهندس. |
+| Solution preparation protocols | `tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md` | `.opencode/agents/application-blueprint.md` | Phases 1–4 operational protocols for مُهندس. SCP-2026-07-28-118. |
+| Solution preparation templates | `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` | `.opencode/agents/application-blueprint.md` | Phase 1–4 output templates for مُهندس. SCP-2026-07-28-118. |
+| Engineering handoff | `project-control/ENGINEERING_HANDOFF_PACKAGE.md` (produced by مُهندس, consumed by Tera) | `.opencode/agents/tera.md` §6 | Two-gate handoff: Solution Readiness → Engineering Intake. |
+| 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 (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. |
+| Token/context policy | `tera-system/TeraTokenPolicy.md` | `.opencode/agents/tera.md` | Runtime contains only startup/loading rules. |
+| Runtime protocols | `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CORE.md` + `TERA_RUNTIME_PROTOCOLS_CLIENT.md` | `.opencode/agents/tera.md` | Detailed operational behavior. Split INS-02 continuation: core (1–11) + client (12–18) + knowledge (19). |
+| Client Discovery protocol | `tera-system/runtime/CLIENT_DISCOVERY_PROTOCOL.md` | `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 18 → reference) | Extracted from §18 of Runtime Protocols; covers full Discovery and Smart Interview. |
+| Domain Intelligence protocol | `tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md` | `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 12 → reference) | Extracted from §12 of Runtime Protocols; covers research, No-Guessing Rule, Source Policy. |
+| Runtime templates | `tera-system/runtime/TERA_RUNTIME_TEMPLATES.md` | Not applicable | Formal output formats only. |
+| 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. |
+| 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. |
+| Project UI/UX executable guide | `project-preparation/28_UI_UX_GUIDELINES.md` using `TERA_RUNTIME_TEMPLATES_DELIVERY.md` Section 33 | `TASK_TEMPLATE.md`, `TeraPreExecutionGate.md` | Final executable visual design rules for EngineeringAgent; raw sources stay in `project-preparation/design-source/`. Split notice INS-02: Section 33 moved to DELIVERY file. |
+| Application proposal template | `tera-workshop/client-templates/commercial/APPLICATION_PROPOSAL_TEMPLATE.md` | `TERA_RUNTIME_TEMPLATES.md` (Section 26) | Formal proposal document. Generated after Client Discovery before formal preparation. |
+| Scope of Work template | `tera-workshop/client-templates/commercial/SCOPE_OF_WORK_TEMPLATE.md` | — | Formal SOW document — scope, deliverables, timeline, payment, assumptions, sign-off. Generated after proposal approval. |
+| Technical Proposal template | `tera-workshop/client-templates/commercial/TECHNICAL_PROPOSAL_TEMPLATE.md` | — | Technical architecture, stack, hosting, security, testing, CI/CD. Generated after SOW approval. |
+| Change Request form | `tera-workshop/client-templates/contractual/CHANGE_REQUEST_FORM.md` | — | Change management — description, impact analysis, revised estimates, approval. Used during execution. |
+| Software Services Agreement | `tera-workshop/client-templates/contractual/SOFTWARE_SERVICES_AGREEMENT_TEMPLATE.md` | — | 18-section legal agreement covering scope, obligations, payment, IP, confidentiality, liability, termination. Arabic, Jordanian law. |
+| Quotation | `tera-workshop/client-templates/commercial/QUOTATION_TEMPLATE.md` | — | Formal price quotation — items, totals, payment terms, sign-off. |
+| Meeting Report | `tera-workshop/client-templates/pre-contract/MEETING_REPORT_TEMPLATE.md` | — | Meeting minutes — attendees, agenda, decisions, action items. |
+| Status Report | `tera-workshop/client-templates/contractual/STATUS_REPORT_TEMPLATE.md` | — | Periodic status — progress, achievements, risks, next steps. |
+| Handover Report | `tera-workshop/client-templates/handover/HANDOVER_REPORT_TEMPLATE.md` | — | Delivery and acceptance — deliverables checklist, access info, sign-off. |
+| Completion Certificate | `tera-workshop/client-templates/handover/COMPLETION_CERTIFICATE_TEMPLATE.md` | — | Formal project completion certificate with seal and signatures. |
+| Client Intake Form | `tera-workshop/client-templates/pre-contract/CLIENT_INTAKE_FORM.md` | — | Pre-interview questionnaire — company, project, goals, budget, tech. |
+| Project Charter | `tera-workshop/client-templates/commercial/PROJECT_CHARTER_TEMPLATE.md` | — | Project initiation document — objectives, scope, team, risks, success criteria. |
+| User Persona Matrix | `tera-workshop/client-templates/pre-contract/USER_PERSONA_MATRIX_TEMPLATE.md` | — | User roles and persona cards — goals, pain points, permissions, features. |
+| Gap Analysis | `tera-workshop/client-templates/pre-contract/GAP_ANALYSIS_TEMPLATE.md` | — | As-is vs to-be analysis, gap identification, recommendations. |
+| Risk Register | `tera-workshop/client-templates/pre-contract/RISK_REGISTER_TEMPLATE.md` | — | Risk tracking — impact, probability, mitigation, owner, status. |
+| SLA | `tera-workshop/client-templates/contractual/SLA_TEMPLATE.md` | — | Service Level Agreement — support hours, response times, priorities. |
+| NDA | `tera-workshop/client-templates/pre-contract/NDA_TEMPLATE.md` | — | Non-Disclosure Agreement — confidentiality, exclusions, governing law. |
+| Client Satisfaction Survey | `tera-workshop/client-templates/handover/CLIENT_SATISFACTION_SURVEY_TEMPLATE.md` | — | Post-project feedback — ratings, open questions, recommendation. |
+| Agent improvement suggestions (AIS) | `tera-system/AIS_PROTOCOL.md` | `project-control/AGENT_IMPROVEMENT_SUGGESTIONS.md` | Protocol + central log for agent self-improvement suggestions from real work. Agents record; Hares processes; Majed approves. |
+| User guide | `tera-system/TERA_USER_GUIDE.md` | Not applicable | User-facing prompts and usage examples. |
+| System maintenance | `tera-system/TeraSystemMaintenanceChecklist.md` | `.opencode/agents/tera.md` | Use when modifying Tera itself. |
+| Agent dependency map | `tera-system/AGENT_DEPENDENCY_MAP.md` | `tera-system/AGENT_DEPENDENCY_MAP.md` | Cross-references between agent files; safe edit order; file size alerts. Read before editing any agent file. |
+| Engineering agent core | `tera-system/engineering-helpers/engineering-agent-core.md` | `.opencode/agents/engineering-agent.md`, `.opencode/agents/engineering-agent-dotnet.md` | Shared engineering rules for ALL engineering agents. Must be read before every task. |
+| .NET Engineering agent | `.opencode/agents/engineering-agent-dotnet.md` | `tera-system/TeraSubAgents.md`, `tera-system/AGENT_ACTIVATION_MATRIX.md`, `tera-system/AGENT_DEPENDENCY_MAP.md` | Specialized .NET/C# engineering agent. Used for .NET tasks instead of the general engineering-agent.md. |
+| Scenario stress tests | `tera-system/TeraScenarioStressTests.md` | Not applicable | Used for validation, not daily runtime. |
+| Client workspace guide | `clients/README.md` | Not applicable | Folder usage guide only; policies remain in `tera-system/`. |
+| Project implementation knowledge | `.opencode/agents/project-knowledge-agent.md` | `.opencode/agents/tera.md` | Post-acceptance knowledge updates only; pre-task reading gate before modification |
+| Project knowledge directory | `clients/.../applications/*/project-knowledge/` | — | Per-application folder; concise operational knowledge per screen/module/service. Not for human-facing docs. |
+| TCEA — Dual-Track Model (SCP-2026-07-29-001) | `.opencode/agents/tera-client-engagement.md` (A.0.3, A.4) | `tera-system/client-helpers/tera-client-engagement-protocols.md`, `pricing.md`, `gates.md`, `discovery-domains.md` | Dual-Track: Track A (Custom Development) موجود + تحسينات Existing App. Track B (Product Implementation) جديد — 6 مراحل (B1–B6) + 6 بوابات (PB.1–PB.6) + 3 بروتوكولات (Product Demo, Fit-Gap, Config-First) + Product Pricing Models. |
+| Track B — Product Demo Protocol | `tera-system/client-helpers/tera-client-engagement-protocols.md` (B.1) | Not applicable | بروتوكول العرض التوضيحي للمنتج للمرحلة B1 من Track B. |
+| Track B — Fit-Gap Analysis Protocol | `tera-system/client-helpers/tera-client-engagement-protocols.md` (B.2) | Not applicable | بروتوكول تحليل الفجوة الرباعي (Fit/Gap-Config/Gap-Custom/Process Change) للمرحلة B2 من Track B. |
+| Track B — Configuration-First Mandate | `tera-system/client-helpers/tera-client-engagement-protocols.md` (B.3) | Not applicable | قاعدة "التكوين أولاً قبل التخصيص" لـ Track B. |
+| Track B — Product Pricing Models | `tera-system/client-helpers/tera-client-engagement-pricing.md` (Product Pricing) | `.opencode/agents/tera-client-engagement.md` (A.8) | نماذج تسعير Track B: تراخيص + خدمات تنفيذ + Retainer + T&M. منفصلة عن TeraPricingPolicy.md |
+| Track B — Gates (PB.1–PB.6) | `tera-system/client-helpers/tera-client-engagement-gates.md` (PB.1–PB.6) | `.opencode/agents/tera-client-engagement.md` (D.1) | بوابات Track B الست: Product Discovery, Fit-Gap Coverage, Solution Blueprint, Configuration Readiness, Go-Live Readiness, Hypercare Handoff. |
+| Track B — Existing App Enhancement | `tera-system/client-helpers/tera-client-engagement-discovery-domains.md` (توجيهات Existing) | `.opencode/agents/tera-client-engagement.md` (A.4) | توجيهات إضافية لـ Track A عند `[Existing]` — أسئلة عن قاعدة الكود، Tech Debt، قيود التكامل. |
+| 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. |
+
+## 4. Duplication Policy
+
+Allowed duplication:
+
+- Short critical rules in `.opencode/agents/tera.md`.
+- Short conduct-gate references in `.opencode/agents/*.md`.
+- Checklist references in runtime files.
+- User-facing summaries in `TERA_USER_GUIDE.md`.
+
+Forbidden duplication:
+
+- Copying full policy sections into runtime.
+- Rewriting the same mandatory file list in multiple catalog files.
+- Defining conflicting gates in more than one source.
+- Adding new agents in runtime without updating `TeraSubAgents.md`.
+
+## 5. Change Rule
+
+When a rule changes, update the source of truth first, then update only the summaries that are operationally required.
+
+If the change affects runtime behavior, sync `.opencode/agents/tera.md` and update its `Last Synced` date.
+
+If a new policy file, folder role, or lifecycle layer is added, update this file and `TeraArchitectureMap.md` in the same maintenance pass.