@tera-system/core 0.1.0

package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md

@@ -0,0 +1,355 @@
+# Tera Runtime Protocols — Client & Discovery
+
+These are the client-facing and discovery protocols (Sections 12–18) split from TERA_RUNTIME_PROTOCOLS.md via INS-02 continuation (2026-08-01).
+Core operational protocols: `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CORE.md` (Sections 1–11).
+Knowledge management: `tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md` (Section 19).
+
+---
+
+## 12. Domain Intelligence and Research Protocol
+
+→ **انتقل إلى ملف منفصل:** `tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md`
+→ يحتوي: قواعد Domain Intelligence، No-Guessing Rule، Source Policy، مستويات البحث، وكل الإجراءات المرتبطة.
+
+---
+
+## 13. Application Discovery Protocol
+
+> ⚠️ **انتقلت ملكية Phase 1 discovery إلى مُهندس (SCP-118).** البروتوكول الكامل الآن في:
+> `tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md` §1.1
+>
+> TeraAgent (Phase 5–7) لا يدير discovery. يحتفظ بهذا القسم كمرجع تاريخي فقط.
+
+Application Discovery was the required dialogue and documentation phase when a user starts a new application idea or provides incomplete/unclear app information.
+
+Core rules:
+
+```text
+No undocumented materially important discovery.
+No project preparation before documented and confirmed understanding.
+No detailed execution planning or TASK-ID generation before `PROJECT_MASTER_PLAN.md` (including the formal phased roadmap) is approved.
+```
+
+Entry triggers:
+
+- User starts a new application idea.
+- User provides scattered or informal app notes.
+- Required `project-inputs` files are missing or materially incomplete.
+- Existing app understanding is unclear, contradictory, or not confirmed.
+
+Conversation rules:
+
+- Enter `Intake Collection Mode`.
+- Ask short batches of questions based on missing information.
+- Do not ask all discovery questions at once.
+- Normalize user statements instead of copying raw chat blindly.
+- Help the user understand the app by summarizing, organizing, and asking important questions.
+- Do not propose major improvements before Tera can summarize the app accurately.
+- Suggestions must be options, not automatic requirements.
+
+Documentation rules:
+
+- Document normalized discovery information in official `project-inputs` files.
+- At minimum, maintain:
+  - `project-inputs/01_APPLICATION_IDEA.md`
+  - `project-inputs/02_TECHNICAL_CONTEXT.md`
+- Additional intake files may be used only when helpful, such as:
+  - `project-inputs/03_USER_PREFERENCES.md`
+  - `project-inputs/04_INITIAL_ASSUMPTIONS.md`
+  - `project-inputs/05_OPEN_QUESTIONS.md`
+- No materially important application information may remain only in chat after discovery.
+- Materially important means information that affects scope, MVP/later phasing, users, workflows, permissions, data, integrations, technical context, constraints, risks, assumptions, open questions, or acceptance.
+- Do not block discovery just to preserve every minor phrase, aside, preference wording, or non-impactful detail.
+- If materially important chat-only information remains undocumented, discovery remains open.
+
+Mandatory feature classification:
+
+- **Before writing the MVP scope into intake files, Tera must run the classification protocol defined in `tera-system/runtime/MVP_DEFINITION_PROTOCOL.md`.**
+- Collect all candidate features from discovery.
+- For each feature, classify by necessity, dependency, risk, cost, and implementation size into one of: Core MVP (Phase 1A) / Extended MVP (Phase 1B) / Phase 2 / Phase 3 / Later / Out of Scope.
+- **User-selected features during discovery are not automatically MVP.**
+- Document the classified list in `project-inputs/01_APPLICATION_IDEA.md` under the appropriate sub-sections.
+- The classification must be visible in the Application Understanding Summary for user review.
+- The user may reclassify, but the default is Tera's analysis-based classification.
+
+Understanding confirmation:
+
+1. Tera creates an `Application Understanding Summary` using `TERA_RUNTIME_TEMPLATES.md`.
+2. Tera asks the user to confirm or correct the summary.
+3. If the user corrects it, Tera updates official intake files.
+4. Tera does not move to project preparation until understanding is minimally confirmed.
+
+Suggestion timing:
+
+- Tera may suggest improvements only after it sufficiently understands the application.
+- Each suggestion must be classified as MVP / Later / Out of Scope / Needs User Decision.
+- Tera must explain why the suggestion matters and must not push it as required scope.
+
+Domain Intelligence handoff:
+
+- After initial understanding is confirmed, Tera decides whether Domain Intelligence is needed.
+- Domain Intelligence is optional and trigger-based.
+- If research/domain analysis produces meaningful improvements or changes, Tera must return to the user with a `Research-Based Improvements Review`.
+- Only agreed or Tera-approved findings may update project inputs or preparation scope.
+
+Phased roadmap approval:
+
+- After discovery and optional Domain Intelligence, Tera creates a `Phased Application Roadmap`.
+- Tera decides what belongs in Phase 1 / MVP and what belongs in later phases.
+- The discovery roadmap is a preliminary scope/phasing agreement.
+- During Phase 5, it is formalized inside `project-control/PROJECT_MASTER_PLAN.md` as the official implementation roadmap.
+- The user must approve `PROJECT_MASTER_PLAN.md` before detailed execution planning or `TASK-COD-*` generation.
+
+Exit criteria:
+
+- Available materially important user information has been collected.
+- Materially important information is documented in `project-inputs`.
+- Application Understanding Summary is confirmed or minimally approved.
+- Domain Intelligence is completed, deferred, or marked not needed.
+- Research-based changes were reviewed with the user when applicable.
+- Phased roadmap is approved.
+
+Reopen discovery when:
+
+- A major ambiguity appears.
+- A project rule or user statement conflicts with the current understanding.
+- Domain research reveals a significant gap.
+- The user changes the app idea, MVP, roles, workflow, or technology materially.
+
+Forbidden actions:
+
+- Do not start `project-preparation/` before documented discovery and user confirmation.
+- Do not leave materially important discovery information only in chat.
+- Do not ask large question dumps.
+- Do not run open-ended domain research before initial understanding unless the user explicitly asks for reference-based discovery.
+- Do not move to detailed execution planning or `TASK-COD-*` generation before `PROJECT_MASTER_PLAN.md` approval.
+
+---
+
+## 14. Client Approval Workflow Protocol
+
+> ⚠️ **TCEA owns client approval.** TeraAgent (Phase 5–7) يتحقق فقط من Execution Authorization قبل Build Mode.
+> هذا القسم مرجعي. البروتوكولات النشطة في ملفات TCEA و TeraClientPolicy.md.
+
+Use this protocol for every external client project.
+
+Authority references:
+
+- `tera-system/TeraClientPolicy.md`
+
+Workspace rule:
+
+```text
+clients/CLIENT-[client-name-or-id]/applications/APP-[app-name-or-id]/
+```
+
+Required stages:
+
+1. Register or update the client folder.
+2. Create or update `CLIENT_PROFILE.md`.
+3. Create or update `CONTACTS.md`.
+4. Identify the application folder under `applications/`.
+5. Collect client discovery answers through Majed.
+6. Produce the mandatory client approval package under `client-approval/`.
+7. Review the package for client-facing clarity and scope control.
+8. Ask Majed to confirm what was approved by the client.
+9. Record approval status in `10_CLIENT_APPROVAL_RECORD.md`.
+10. Allow Build Mode only after Execution Authorization is approved and recorded.
+
+Mandatory approval gates:
+
+| Gate | Requirement |
+|---|---|
+| Idea Approval | The client confirms the idea is understood. |
+| Scope Approval | The client confirms in-scope, out-of-scope, and deferred items. |
+| Flow Approval | The client confirms the main flows. |
+| Screen Approval | The client confirms screen list and purpose. |
+| Design Direction Approval | The client confirms style, tone, references, and constraints. |
+| Prototype Approval | The client confirms the prototype or the reason no prototype is needed. |
+| Execution Authorization | The client authorizes implementation to start. |
+
+Client question rules:
+
+- Ask short question sets that Majed can forward to the client.
+- Separate confirmed facts from suggestions.
+- Do not ask for every possible detail at once.
+- Ask first for approval authority, scope, flows, screen expectations, and visual direction.
+- If the client is non-technical, use business language rather than technical terms.
+
+Client-facing document rules:
+
+- Default language is Arabic.
+- Do not mention Tera internals, sub-agents, runtime files, token policy, or orchestration mechanics.
+- Include assumptions, exclusions, pending decisions, and approval status.
+- Do not promise unconfirmed timelines, costs, third-party integrations, or platform capabilities.
+
+Implementation restrictions:
+
+- Do not create implementation tasks for client work before the client approval package is complete and Execution Authorization is approved.
+- Do not build final UI before design direction is approved.
+- Do not expand scope unless a change record exists and is approved.
+- Internal technical spikes require explicit user authorization, must remain non-deliverable research, must not modify final application code, and must not become client deliverable scope without approval.
+
+Change handling:
+
+1. Record the request in `client-approval/11_CHANGE_CONTROL.md`.
+2. Classify it as Clarification, Minor Adjustment, Enhancement, New Scope, Phase 2, or Rejected.
+3. If it affects execution, also record the related decision or issue in `project-control/`.
+4. Do not implement `Enhancement` or `New Scope` without documented approval.
+
+Exit criteria before Build Mode:
+
+- Client profile exists.
+- Contacts exist.
+- Approval authority is documented or explicitly confirmed by the user.
+- Client approval package exists.
+- Scope, flows, screen map, design direction, acceptance criteria, and execution authorization are approved and recorded.
+- Only truly non-applicable package files, such as prototype notes for a no-prototype project, may be marked `Not applicable with reason`; approval gates required for execution must not be waived.
+- Pending decisions are documented and do not block the next phase.
+
+---
+
+## 15. Handoff Readiness Gate
+
+Purpose: Determine when a phase or task group is ready for using `DocumentationHandoverAgent`.
+
+Important: `Handoff Readiness Gate` is not required for normal internal task handbacks. It is only for evaluating phase readiness, Release readiness, or formal documentation/delivery packages.
+
+### When to use
+
+- Before internal handoff.
+- Before Release.
+- After completing a stable set of screens.
+- After closing a Phase.
+- When a run guide, user manual, or delivery summary is needed.
+
+### Must Pass
+
+1. The phase or screen set is stable.
+2. All core TASKs for the phase are closed or clearly classified.
+3. No blocking Issues remain open.
+
+If any Must Pass item fails:
+- Do not run `DocumentationHandoverAgent` for final delivery.
+- May only run it for an internal draft if Tera decides so and documents the reason.
+
+### Should Pass
+
+4. `DECISIONS_LOG.md` is updated.
+5. `PROJECT_STATE.md` is updated.
+6. `TERA_ACTIVE_CONTEXT.md` is updated.
+7. Run instructions are clear.
+8. Required accounts or permissions are documented without secrets.
+9. Deferred notes are listed as `Known Limitations`.
+10. Documentation type is clear: internal / delivery / Release-facing.
+
+Rule:
+- `Must Pass` blocks handoff readiness.
+- `Should Pass` may be bypassed only with a documented reason.
+
+---
+
+## 16. Plan Compliance Review
+
+`PlanComplianceReviewAgent` is a compliance reviewer, not a manager above Tera.
+
+### Purpose
+
+Compare actual execution against:
+- `PROJECT_MASTER_PLAN.md`
+- `PROJECT_DETAILED_EXECUTION_PLAN.md`
+- `TASK_REGISTRY.md`
+- `ISSUES_AND_GAPS.md`
+- `DECISIONS_LOG.md`
+- Related task files or references when needed
+
+Detect:
+- implemented items
+- partially implemented items
+- items needing fix before acceptance
+- intentionally deferred items
+- cancelled or out-of-scope items
+- deviations from the plan
+- inconsistencies between the plan and execution records
+
+### When to use
+
+- End of a major or minor Phase.
+- After a large task batch.
+- Before MVP acceptance.
+- Before handoff/release acceptance.
+- When roadmap drift is suspected.
+
+### When not to use by default
+
+- After every small task.
+- As a replacement for `qa-agent`.
+- As a replacement for `QualityReviewCoordinatorAgent`.
+- As a replacement for `ProjectControlAgent`.
+
+### Relationship with other agents
+
+- `qa-agent`: reviews task/screen/workflow acceptance.
+- `QualityReviewCoordinatorAgent`: reviews periodic multi-domain quality.
+- `PlanComplianceReviewAgent`: reviews roadmap and plan compliance.
+- Tera remains the final decision owner for status updates, task creation, issue creation, and phase acceptance.
+
+### Required report format
+
+```text
+Plan Compliance Report
+- Reviewed Phase / Batch
+- Planned Items Confirmed
+- Implemented but Not Accepted
+- Needs Fix Before Acceptance
+- Deferred / Cancelled / Out of Scope Items
+- Missing or Unclear Plan Coverage
+- Off-Plan Work Detected
+- Linked Tasks / Issues / Decisions Reviewed
+- Tera Decisions Needed
+```
+
+---
+
+## 17. Sub-Agent Status Review
+
+Tera maintains a lightweight file at:
+
+```text
+project-control/SUB_AGENT_STATUS.md
+```
+
+Purpose: Track sub-agent usage, load, quality, update need, and potential merge or deactivation.
+
+### Rules
+
+- Tera is the final evaluator.
+- `ProjectControlAgent` may only help collect data or update the file when Tera explicitly requests it.
+- The file must remain compact and non-archival. It must not become a copy of `PROJECT_ACTIVITY_LOG.md`.
+- Do not issue a strong judgment (e.g. `Needs Update`, `Overloaded`, `Candidate for Merge`) based on a single incident unless the problem is clearly structural and obvious.
+
+### When to update
+
+- After every 3-5 tasks.
+- At the end of each Phase.
+- When adding, activating, or deactivating an agent.
+- When an error repeats or visible pressure appears on an agent.
+- Before starting a new medium or large project.
+
+### Mandatory separation within evaluation
+
+- `Status` = agent's operational state within the project.
+- `Quality` = output quality of the agent.
+- `Decision / Notes` = what Tera decides about the agent.
+
+If the review produces an important administrative decision, it may also be recorded in `DECISIONS_LOG.md`.
+
+---
+
+## 18. Client Discovery and Smart Interview Protocol
+
+→ ⚠️ **ملكية مُهندس (SCP-118).** البروتوكول الكامل:
+→ `tera-system/runtime/CLIENT_DISCOVERY_PROTOCOL.md`
+→ بروتوكولات التحضير: `tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md`
+
+---