@tera-system/core 0.1.0

package/core/tera-system/TeraProjectIntakePolicy.md

@@ -0,0 +1,164 @@
+# Project Intake Policy
+
+## 1. Purpose
+
+This policy defines the intake process before formal project preparation for any new project.
+
+**SCP-2026-07-28-118:** Phase 1 intake is now owned by ApplicationBlueprintAgent (مُهندس). TeraAgent handles Engineering Intake (Phase 5).
+
+The intake process has two sequential stages:
+
+```
+Stage 1: Client Discovery Mode  ← Open conversation + understanding summary
+Stage 2: Smart Interview         ← Structured adaptive questioning (only if gaps remain)
+```
+
+These are defined in `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md` Section 18, with the question bank at `tera-system/TeraApplicationQuestionBank.md`.
+
+The **Project Intake Gate** checks whether the information collected during these stages is ready for formal preparation.
+
+## 2. Required Intake Files
+
+The minimum intake package is:
+
+- `project-inputs/01_APPLICATION_IDEA.md`
+- `project-inputs/02_TECHNICAL_CONTEXT.md`
+
+For external client projects, Tera must also collect or create the client workspace records defined in `tera-system/TeraClientPolicy.md`:
+
+- `clients/CLIENT-[client-name-or-id]/CLIENT_PROFILE.md`
+- `clients/CLIENT-[client-name-or-id]/CONTACTS.md`
+- `clients/CLIENT-[client-name-or-id]/applications/APP-[app-name-or-id]/client-approval/`
+
+## 3. Application Idea File
+
+`project-inputs/01_APPLICATION_IDEA.md` should capture at minimum:
+
+- application description
+- problem being solved
+- expected users
+- main workflows
+- expected modules or screens
+- required outputs
+- MVP scope
+- out-of-scope items
+- user notes and open questions
+
+## 4. Technical Context File
+
+`project-inputs/02_TECHNICAL_CONTEXT.md` should capture at minimum:
+
+- programming language
+- framework
+- application type
+- database
+- ORM / data access approach
+- package manager / CLI
+- UI framework or design system if known
+- required external libraries
+- forbidden libraries or technologies
+- runtime environment
+- deployment or hosting notes if known
+- technical or security constraints
+- technology profile candidate
+
+## 5. Intake Readiness Status
+
+Use these statuses:
+
+- `Missing`
+- `Partial`
+- `Complete`
+
+## 6. Intake Collection via Client Discovery + Smart Interview
+
+If one or both intake files are missing or materially incomplete, Tera must enter:
+
+```text
+Client Discovery Mode
+```
+
+This is a **two-stage process** defined in `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 18):
+
+### Stage 1: Client Discovery (mandatory first step)
+1. **Open Listening** — Let the client explain freely without interruption.
+2. **Understanding Summary** — Summarize Tera's understanding and ask: "هل هذا الفهم صحيح؟"
+3. **Confirmation** — Do not proceed until the client confirms or corrects.
+4. **Decision** — If the picture is clear enough, proceed to Intake Gate. If major gaps remain, proceed to Stage 2.
+
+### Stage 2: Smart Interview (if gaps remain)
+1. **Opening Round** — Essential questions from Domains 1, 2, 4 (5–7 questions).
+2. **Analysis** — Identify gaps and select next domain.
+3. **Adaptive Rounds** — Continue in small batches until picture is complete.
+4. **Final Understanding Summary** — Confirm with the user.
+5. **Suggestions and Improvements** — Propose improvements, classified separately from scope.
+
+### Rules for both stages
+
+- Do not start formal `project-preparation/` output.
+- Do not create `TERA_PROJECT_DECISION.md`.
+- Do not choose a final active Technology Profile.
+- Do not generate sub-agents for implementation work.
+- Do not create implementation `TASK-ID`s.
+- Document each answer immediately in `project-inputs/`.
+- For external client projects, phrase questions for Majed to forward to the client.
+- **When the client does not know**: propose a suitable default, document it as an `Assumption` (not as a final decision). See Question Bank for assumption documentation format.
+
+## 7. Minimum Questions
+
+When intake is incomplete, Tera should ask only the shortest useful questions, such as:
+
+- What is the application idea?
+- Who will use it?
+- What are the three most important workflows?
+- Is the technology already decided?
+- If not, should Tera propose it later?
+- What database is required, if any?
+- Is there any preferred or forbidden UI/design direction?
+
+For external client projects, also ask the shortest useful client questions:
+
+- What is the client name?
+- Is the client an individual, company, or organization?
+- Who are the client contacts, and who can approve decisions?
+- What phone numbers or emails are available, if any?
+- 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?
+
+## 8. When Tera Can Proceed
+
+ApplicationBlueprintAgent (مُهندس — SCP-2026-07-28-118) may proceed to formal preparation only when:
+
+- `01_APPLICATION_IDEA.md` exists and is acceptable at minimum level.
+- `02_TECHNICAL_CONTEXT.md` exists and is acceptable at minimum level, or clearly documents that the stack is still undecided.
+- Tera has determined whether an existing Technology Profile can be used, or whether a new profile draft will be needed later.
+
+For external client projects, Tera may proceed only to client approval preparation when:
+
+- client profile and contacts are documented at minimum level.
+- approval authority is known or explicitly marked as unknown.
+- 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.
+
+## 9. Relationship with 00_PROJECT_INPUTS.md
+
+`project-preparation/00_PROJECT_INPUTS.md` is not a replacement for the intake files.
+
+It is Tera's normalized preparation summary derived from:
+
+- `project-inputs/01_APPLICATION_IDEA.md`
+- `project-inputs/02_TECHNICAL_CONTEXT.md`
+
+## 10. Final Rule
+
+```text
+No Intake = No Project Preparation
+No Technical Context = No Active Technology Profile
+No Active Technology Profile = No Implementation
+No documented client context = No client project preparation
+No Client Approval Package = No Implementation
+```

package/core/tera-system/TeraScenarioStressTests.md

@@ -0,0 +1,168 @@
+# Tera Scenario Stress Tests
+
+## 1. Purpose
+
+This file defines test scenarios used to validate Tera behavior after system changes.
+
+These scenarios are not project requirements. They are system validation cases.
+
+## 2. How To Use
+
+For each scenario, run Tera in Plan Mode first and verify:
+
+- correct files are read
+- correct gates are applied
+- missing information is requested
+- no implementation starts early
+- client approval rules are respected when applicable
+- decisions are documented in the proper location
+
+## 3. Scenario A: New Client With Incomplete Idea
+
+Input:
+
+```text
+عميل جديد يريد تطبيق لإدارة الصيانة، لكن لا توجد تفاصيل كافية.
+لا توجد تقنية محددة.
+لا توجد بيانات تواصل كاملة.
+```
+
+Expected behavior:
+
+- Enter Client Discovery and Intake Collection Mode.
+- Ask short questions for client profile, contacts, approval authority, idea, users, workflows, and technical context.
+- Create or update `project-inputs/` only after answers are available.
+- Prepare `clients/CLIENT-*/` structure when client identity is known.
+- Do not create implementation tasks.
+- Do not enter Build Mode.
+
+Pass criteria:
+
+- No `project-preparation/` formal output before minimum intake readiness.
+- No implementation without technical context and client approval package.
+
+## 4. Scenario B: Client Requests Scope Change After Approval
+
+Input:
+
+```text
+Client approval package is approved.
+Client now asks to add online payments and WhatsApp integration.
+```
+
+Expected behavior:
+
+- Do not implement directly.
+- Record request in `client-approval/11_CHANGE_CONTROL.md`.
+- Classify as `Enhancement` or `New Scope`.
+- Ask Majed for client approval decision.
+- If approved, update related project-control decision/issue/task records.
+
+Pass criteria:
+
+- No scope expansion without approved change record.
+- Existing approved scope remains traceable.
+
+## 5. Scenario C: Design Ambiguity Before UI Build
+
+Input:
+
+```text
+Client approved scope, but design direction is unclear.
+Implementation request includes dashboard UI.
+```
+
+Expected behavior:
+
+- Block final UI implementation.
+- Ask for design direction or references.
+- Update `client-approval/07_DESIGN_DIRECTION.md` and internal UI guidance when needed.
+- Keep work in Plan Mode until design direction is approved.
+
+Pass criteria:
+
+- No invented UI style.
+- No final UI implementation before design direction approval.
+
+## 6. Scenario D: Conflict Between Client Approval And Internal Plan
+
+Input:
+
+```text
+Client approval excludes reports.
+Internal implementation plan includes reports in Phase 1.
+```
+
+Expected behavior:
+
+- Stop affected work only.
+- Trigger contradiction resolution.
+- Identify conflicting sources.
+- Ask Majed for decision.
+- Update approval record, preparation files, or project-control decisions after resolution.
+
+Pass criteria:
+
+- No implementation proceeds on conflicting scope.
+- Resolution is documented.
+
+## 7. Scenario E: Runtime Maintenance Change
+
+Input:
+
+```text
+Tera policy changes Build Mode requirements.
+```
+
+Expected behavior:
+
+- Update source of truth first.
+- Check `TeraPolicyMap.md`.
+- Decide whether `.opencode/agents/tera.md` needs sync.
+- Update `Last Synced` if runtime changes.
+- Run maintenance checklist.
+
+Pass criteria:
+
+- No policy/runtime divergence remains.
+- Runtime stays compact.
+
+## 8. Scenario F: Existing Project Resume
+
+Input:
+
+```text
+User resumes a project after a break and asks for next step.
+```
+
+Expected behavior:
+
+- Read `project-control/TERA_ACTIVE_CONTEXT.md` first if present.
+- Read only needed official files after that.
+- Summarize current state and next safe step.
+- Do not restart intake or rebuild the plan unless records are missing or contradictory.
+
+Pass criteria:
+
+- No broad file reading without reason.
+- No duplicate preparation from scratch.
+
+## 9. Scenario G: Missing Technology Profile
+
+Input:
+
+```text
+Project idea and client approval are ready, but the technical stack is undecided or no matching profile exists.
+```
+
+Expected behavior:
+
+- Do not create implementation tasks.
+- Read `project-inputs/02_TECHNICAL_CONTEXT.md` and relevant architecture files.
+- If stack is undecided, ask Majed for a decision or document that Tera should propose options later.
+- If stack is known but no profile exists, draft one from `tera-system/profiles/TEMPLATE.md` and ask for approval.
+
+Pass criteria:
+
+- No CLI commands, implementation tasks, or Engineering delegation before active profile approval.
+- The missing profile decision is documented.