@tera-system/core 0.1.0

package/core/tera-system/TeraArchitectureMap.md

@@ -0,0 +1,91 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# Tera Architecture Map
+
+## 1. Purpose
+
+This file describes Tera as an operating system for client and software project delivery.
+
+It is a map, not a policy source. Rules remain in the files listed in `TeraPolicyMap.md`.
+
+## 2. Architectural Layers
+
+| Layer | Responsibility | Main files/folders |
+|---|---|---|
+| Identity and authority | Defines Tera role, authority, runtime order, decision ownership, and core agent conduct gate | `.opencode/agents/tera.md`, `TERA_AGENT_CONDUCT.md` |
+| Strategic advisory and decision support | Helps Majed evaluate whether a decision, project, fork, or direction is right before execution; advisory only, no approval or execution authority | `.opencode/agents/tera-strategic-advisor.md` |
+| Project intake | Captures raw idea, technical context, missing information, and readiness | `TeraProjectIntakePolicy.md`, `project-inputs/` |
+| Client engagement and approval | Manages client profile, contacts, approval package, and change control — the commercial truth layer | `TeraClient*.md`, `clients/`, `.opencode/agents/tera-client-engagement.md` |
+| Solution preparation (phases 1–4) | Owned by مُهندس (ApplicationBlueprintAgent). Converts confirmed handoff into blueprint, intake, project decision, preparation planning, delegation, cross-review, baseline, and Engineering Handoff Package | `.opencode/agents/application-blueprint.md`, `Tera_Project_Preparation_Files.md`, `project-preparation/`, `runtime/TERA_SOLUTION_PREPARATION_*.md` |
+| Design governance | Controls design source decisions, design tokens, component rules, internal kits, and UI acceptance | `tera-system/design-system/`, `project-preparation/28_UI_UX_GUIDELINES.md` |
+| Engineering handoff gate | Two-gate handoff between مُهندس and Tera: Solution Readiness Gate → Engineering Handoff Package → Engineering Intake Gate | `ENGINEERING_HANDOFF_PACKAGE.md`, `project-control/` |
+| Execution orchestration (phases 5–7) | Owned by TeraAgent (Engineering Delivery Lead). Execution planning, delegation to Coding/QA/Audit agents, Pre/Post gates, implementation, delivery, closure | `TeraPreExecutionGate.md`, `runtime/TERA_RUNTIME_*.md`, `project-control/` |
+| Technical specialization | Keeps stack-specific behavior outside the generic Tera system | `tera-system/profiles/` |
+| Domain knowledge specialization | Keeps reusable domain knowledge references outside generic agent prompts | `tera-system/knowledge-base/` |
+| Sub-agent lifecycle | Defines, generates, narrows, activates, and reviews specialized agents | `TeraSubAgents.md`, `AGENT_GENERATION_TEMPLATE.md`, `generated-agents/` |
+| Delivery, handoff, and closure | Produces final delivery readiness, release notes, client handover material, acceptance records, and closure reports | `project-control/DELIVERY_READINESS_REPORT.md`, `project-control/PROJECT_CLOSURE_REPORT.md`, `clients/.../delivery/` |
+| Project implementation knowledge | Maintains concise current-state operational knowledge per screen/module/service | `project-knowledge/` داخل كل تطبيق |
+| Tera distribution and versioning | Builds releases and distributes Tera to client repositories in a versioned, verifiable way; clients derive updates from the origin repository (RepositoryUrl) via fetch + verified release packages (Tag + Manifest + SHA lockfile + updater tools); ownership contract separates Tera-managed from client-owned files | `tera-system/TERA_DISTRIBUTION_POLICY.md`, `tera-workshop/tools/tera-fetch.ps1`, `tera-workshop/tools/tera-release.ps1`, `tera-workshop/tools/tera-update.ps1`, `.tera/lock.json` داخل مستودعات العملاء |
+
+## 3. Folder Roles
+
+| Folder | Role | Must not be used for |
+|---|---|---|
+| `tera-system/` | System reference and policies | Project-specific outputs |
+| `.opencode/agents/` | Active runtime agents | Long policy details |
+| `project-inputs/` | Raw or normalized intake inputs | Formal preparation replacements |
+| `project-preparation/` | Solution preparation outputs (مُهندس) | Client-facing approval package |
+| `clients/` | Client records, approval, assets, communications, delivery | Internal-only execution planning |
+| `project-control/` | Task, issue, decision, activity, state tracking; Engineering Handoff Package | Requirements source of truth |
+| `generated-agents/opencode/` | Draft generated agents | Active runtime without review |
+| `tera-system/design-system/` | System design governance, schemas, gates, internal kits | Project-specific design decisions |
+| `tera-system/profiles/` | Technology-specific execution rules | Generic project policy |
+| `tera-system/knowledge-base/` | Reusable domain knowledge references | Project-specific client facts |
+| `tera-system/engineering-helpers/` | Shared engineering reference files | Language-specific profiles |
+| `tera-workshop/` | System development and tooling files | Core policy or project files |
+| `tera-workshop/tools/` | Official Tera updater tooling (tera-update.ps1 + batch updater) used to pin/upgrade Tera in client repositories | Client application code; replacing client-owned files |
+| `book/` | Comprehensive user-facing documentation and guides (Quick Start, Vision, Quality, Policies) | Runtime operational files; per-project records |
+| `architecture/` | Structurizr C4 workspace (`.dsl` source of truth + exported diagrams) | Application code; client project files |
+
+## 4. Core Flow
+
+```text
+Client / User Idea
+-> Owner Strategic Advisory when requested
+-> [External] TCEA: Client Discovery → Pricing → Approval → Handoff
+-> مُهندس: Blueprint + Phases 1–4 → Solution Baseline → Solution Readiness Gate
+-> Engineering Handoff Package
+-> Tera: Engineering Intake Gate → Phase 5 Execution Planning
+-> Phase 6: Delegated Implementation (Coding/QA/Audit agents)
+-> Phase 7: Technical Delivery & Closure
+-> [External] TCEA: client-facing delivery support when requested
+```
+
+## 5. External Client Flow
+
+```text
+Client Registration → Contacts → Application Intake
+→ Client Questions through Majed → Discovery Coverage
+→ Client Approval Package → Approval Record → Execution Authorization
+→ TCEA Handoff to مُهندس
+→ مُهندس: Blueprint + Phases 1–4 → Solution Baseline
+→ Solution Readiness Gate → Engineering Handoff Package
+→ Tera: Engineering Intake Gate → Phases 5–7
+→ Change Control for later requests
+```
+
+## 6. Runtime Design Principle
+
+All core runtime agents must pass the conduct gate in `tera-system/TERA_AGENT_CONDUCT.md`.
+
+`.opencode/agents/tera.md` should answer:
+- What must Tera load now?
+- What is forbidden now?
+- Which policy should Tera read for details?
+- Is Build Mode allowed?
+
+It should not duplicate full policies, templates, or long agent contracts.
+
+## 7. Stability Rule
+
+When the system grows, add new policies only when there is a clear operating gap. Prefer updating maps and existing policies over creating new layers.

package/core/tera-system/TeraClientPolicy.md

@@ -0,0 +1,366 @@
+# Tera Client Policy
+
+> Merged from: `TeraClientEngagementPolicy.md`, `TeraClientApprovalPolicy.md`, `TeraClientChangeControlPolicy.md`, `TeraClientFacingContentPolicy.md` (v1.0)
+
+## 1. Purpose
+
+This policy defines how Tera handles external client projects — from discovery and engagement through approval, change control, and client-facing documentation.
+
+Tera must treat client work as a documented relationship, not only a technical build request.
+
+---
+
+## 2. Core Rules
+
+```text
+Spoken client input is not final until documented.
+No documented client context = No client project preparation.
+No documented approval authority = No final client approval.
+No Client Approval Package = No Implementation.
+No Approved Scope = No Build Mode.
+No Approved Design Direction = No Final UI Implementation.
+No Approved Change Request = No Scope Expansion.
+No Client Handover Package = No client project closure.
+Client approval must be visible in files, not only in chat.
+```
+
+---
+
+## 3. Client Workspace Structure
+
+Client-facing and client-management files belong under:
+
+```text
+clients/
+```
+
+Required structure:
+
+```text
+clients/
+  CLIENT-[client-name-or-id]/
+    CLIENT_PROFILE.md
+    CONTACTS.md
+    applications/
+      APP-[app-name-or-id]/
+        client-approval/
+        client-assets/
+        client-communications/
+        delivery/
+```
+
+Rules:
+
+- Each client must have a dedicated folder.
+- Each client application must have a dedicated application folder.
+- Do not mix client-facing approval material with internal `project-preparation/` files.
+- Do not store secrets, passwords, access tokens, or private credentials in client files.
+- Final client handover material belongs in `clients/CLIENT-*/applications/APP-*/delivery/`.
+
+---
+
+## 4. Required Client Profile
+
+```text
+CLIENT_PROFILE.md
+```
+
+Minimum content:
+
+- client name
+- client type: individual / company / organization
+- business domain
+- default client-facing language: Arabic unless the user decides otherwise
+- technical familiarity: low / medium / high / unknown
+- decision style and communication notes
+- project sensitivity: low / medium / high / critical
+- preferred approval method
+- general relationship notes
+
+---
+
+## 5. Required Contacts File
+
+```text
+CONTACTS.md
+```
+
+Minimum content per contact:
+
+- name
+- role at client side
+- decision authority: decision maker / reviewer / technical contact / finance / other
+- phone number if available
+- email if available
+- preferred communication channel
+- approval authority: yes / no / unknown
+- communication notes
+
+Tera must not treat approval from a contact as final unless that contact has documented approval authority or the user explicitly confirms it.
+
+### Client Discovery Output — Application Proposal
+
+After the Client Discovery + Smart Interview process completes (see `TERA_RUNTIME_PROTOCOLS_CLIENT.md` Section 18), the designated agent (TCEA for external clients, مُهندس for internal projects — SCP-2026-07-28-118) generates a **professional client-facing Application Proposal** as an HTML page using `tera-workshop/APPLICATION_PROPOSAL_TEMPLATE.html`.
+
+The proposal captures: understanding, users & roles, scope (MVP + out-of-scope), requirements by domain, assumptions, and proposed roadmap. Generated from `tera-workshop/APPLICATION_PROPOSAL_TEMPLATE.html`.
+
+The proposal is saved under `clients/.../client-approval/` and **must be approved by the client** before formal preparation begins. The approved proposal becomes the official scope reference for all subsequent gates.
+
+---
+
+## 6. Client Discovery
+
+When a new external client project starts, Tera must enter Client Discovery before implementation.
+
+Client Discovery gathers:
+
+- client identity
+- contacts and approval authority
+- application idea
+- client goals
+- client pain points
+- preferred style and visual direction
+- reference apps, sites, documents, colors, or brand assets
+- non-preferred examples
+- expected approval process
+- budget/time sensitivity if the user chooses to provide it
+- client-specific risks
+
+### Mandatory Discovery Coverage Rule
+
+For external client work managed through `TeraClientEngagementAgent`, confirmed understanding alone is not sufficient.
+
+TCEA must not treat scope, quotation, or handoff outputs as ready until mandatory discovery coverage has been evaluated across the required discovery domains and approved by Majed.
+
+### Discovery Coverage Evidence
+
+Discovery coverage must be visible in files, not only in chat.
+
+Recommended operational evidence:
+
+```text
+clients/.../client-engagement/DISCOVERY_COVERAGE_SUMMARY.md
+```
+
+The file should show:
+- domain coverage status
+- blocking vs non-blocking gaps
+- assumptions
+- readiness decision for scope / quotation / handoff
+
+### Final Rule
+
+```text
+No discovery coverage evidence = no trusted client scope, no trusted quotation basis, and no trusted internal handoff.
+```
+
+### Majed as Client Intermediary
+
+The normal operating model is:
+
+- Tera asks Majed short, direct client questions.
+- Majed asks the client.
+- Majed returns the answers to Tera.
+- Tera documents material answers in the correct files.
+
+Tera must phrase questions so they can be forwarded to the client with minimal editing.
+
+### Improvement Suggestions
+
+Tera may suggest improvements, additions, or simplifications only if they:
+
+- support the client's original goal
+- do not change the core project idea
+- are clearly marked as suggestions
+- are separated from confirmed scope
+- are offered for Majed to review with the client
+
+Suggestions do not become scope until approved and documented.
+
+---
+
+## 7. Client Approval Package
+
+### Location
+
+```text
+clients/CLIENT-[client-name-or-id]/applications/APP-[app-name-or-id]/client-approval/
+```
+
+### Required Files
+
+The default mandatory package is:
+
+- `01_CLIENT_PROJECT_BRIEF.md`
+- `02_CLIENT_PROPOSAL.md`
+- `03_SCOPE_OF_WORK.md`
+- `04_FEATURE_SCOPE_MATRIX.md`
+- `05_USER_FLOWS.md`
+- `06_SCREEN_MAP.md`
+- `07_DESIGN_DIRECTION.md`
+- `08_PROTOTYPE_PLAN.md`
+- `09_ACCEPTANCE_CRITERIA.md`
+- `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.
+
+### Approval Gates
+
+| Gate | Required approval |
+|---|---|
+| Gate 1: Idea Approval | The client confirms the project idea is understood correctly. |
+| Gate 2: Scope Approval | The client confirms what is in scope, out of scope, and deferred. |
+| 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 7: Execution Authorization | The client authorizes moving into implementation. |
+
+### Approval Record
+
+`10_CLIENT_APPROVAL_RECORD.md` must document:
+
+- client name
+- application name
+- approval date or pending status
+- approving contact
+- approval authority evidence or user confirmation
+- approved files
+- pending decisions
+- rejected or deferred items
+- execution authorization status
+
+### Relationship to Internal Implementation
+
+Implementation tasks must trace back to approved scope and acceptance criteria.
+
+Tera must not create implementation `TASK-ID`s for client work before Gate 7 passes.
+
+If Majed explicitly authorizes a pre-approval technical spike, it must be treated as non-deliverable research only, must not modify final application code, must not become client scope, and must be documented separately from Build Mode.
+
+---
+
+## 8. Change Control
+
+```text
+No undocumented change requests during execution.
+```
+
+### Change Log Location
+
+```text
+clients/CLIENT-[client-name-or-id]/applications/APP-[app-name-or-id]/client-approval/11_CHANGE_CONTROL.md
+```
+
+If a change affects execution tasks, also record the related decision or issue in `project-control/`.
+
+### Change Types
+
+| Type | Meaning | Default action |
+|---|---|---|
+| Clarification | Explains an existing approved item without changing scope | Document and continue |
+| Minor Adjustment | Small change inside approved scope | Document and allow if low risk |
+| Enhancement | Improves an approved feature but adds work | Ask user before adding |
+| New Scope | Adds a new feature, screen, workflow, integration, or data area | Requires explicit approval |
+| Phase 2 | Valuable but not needed for current delivery | Defer |
+| Rejected | Conflicts with project goal, approved scope, or constraints | Do not implement |
+
+### Change Record Format
+
+Each change record must include:
+
+- change ID
+- date
+- requester
+- request summary
+- affected approved file or gate
+- classification
+- scope impact
+- design impact
+- technical impact
+- time/cost impact if known
+- decision: approve / defer / reject / needs client decision
+- approval authority
+- related task or issue if any
+
+### Implementation Restriction
+
+Tera must not implement a change classified as `Enhancement` or `New Scope` until Majed confirms the required client approval and the approval is documented.
+
+For `New Scope`, approval from the documented client approval authority is required unless Majed explicitly records that the item is deferred to a later phase and will not affect the current build.
+
+### Final Rule
+
+```text
+Approved project scope can only change through an approved change record.
+```
+
+---
+
+## 9. Client-Facing Content
+
+### Default Language
+
+Client-facing documents are written in Arabic by default.
+
+Use another language only when Majed explicitly requests it.
+
+### Content Rules
+
+Client-facing content must be:
+
+- clear and readable by non-technical clients
+- concise but complete enough for approval
+- free of internal Tera implementation details
+- free of sub-agent names, internal orchestration details, token policies, or runtime mechanics
+- explicit about scope, assumptions, exclusions, and pending decisions
+- careful not to promise uncertain timelines, costs, integrations, or capabilities
+
+### Separation Rule
+
+Do not expose internal Tera files directly as client documents unless Tera has rewritten them into client-facing form.
+
+Examples:
+
+- `project-preparation/08_TECHNICAL_ARCHITECTURE.md` is internal.
+- `clients/.../client-approval/02_CLIENT_PROPOSAL.md` is client-facing.
+
+### Approval Language
+
+Every approval document must include a clear approval section, such as:
+
+```text
+حالة الاعتماد: معتمد / يحتاج تعديل / مرفوض / بانتظار قرار
+ملاحظات العميل:
+الشخص المعتمد:
+تاريخ الاعتماد:
+```
+
+### Suggestion Language
+
+Suggestions must be marked clearly:
+
+```text
+اقتراح من تيرا - يحتاج موافقة العميل قبل اعتباره ضمن النطاق.
+```
+
+### Final Rule
+
+```text
+Client-facing content must protect clarity, scope, and trust.
+```
+
+---
+
+## 10. Relationship to Internal Tera Files
+
+Client files are official relationship and approval records.
+
+Internal Tera files remain responsible for execution planning:
+
+- `project-inputs/`
+- `project-preparation/`
+- `project-control/`
+
+If a client-facing file conflicts with an internal Tera file, Tera must stop affected work and ask the user to resolve the contradiction.