@tera-system/core 0.1.0

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

@@ -0,0 +1,799 @@
+# Tera Runtime Protocols — Core
+
+These are the core operational protocols (Sections 1–11) split from TERA_RUNTIME_PROTOCOLS.md via INS-02 continuation (2026-08-01).
+Client/discovery protocols: `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Sections 12–18).
+Knowledge management: `tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md` (Section 19).
+
+---
+
+## 1. Runtime Self-Sync Protocol
+
+`.opencode/agents/tera.md` is the complete system reference.
+`.opencode/agents/tera.md` is the active runtime file.
+
+Sync `.opencode/agents/tera.md` when the system reference changes rules about:
+
+- File paths and output locations.
+- Sub-agent generation, specialization, or activation policy.
+- Anti-bloat and scope-control rules.
+- Orchestration lifecycle, Decision Matrix, gates.
+- Model Capability Gate or Security Sensitivity Levels.
+- Roadmap tracking or PlanComplianceReviewAgent.
+- Design Governance Layer or UI Acceptance Gate.
+- Delegation format, handback protocol, or Tera authority.
+- Policy map, architecture map, maintenance checklist, or source-of-truth rules.
+
+Rules:
+- Do not copy the full system reference.
+- Sync only operational rules that affect runtime behavior.
+- Update `Last Synced` in the file header after sync.
+- If no sync is needed, document the reason in the maintenance report.
+
+---
+
+## 2. Generated Sub-Agent Lifecycle Protocol
+
+When sub-agents are needed, generate them only inside:
+
+```text
+generated-agents/opencode/
+```
+
+Also create:
+
+```text
+generated-agents/opencode/GENERATED_AGENTS_MANIFEST.md
+```
+
+For Phase 4 (Sub-Agent Generation & Preparation Delegation), also create:
+
+```text
+project-control/AGENT_DELEGATION_PLAN.md
+```
+
+Phase 4 delegation is for **preparation-file creation only**. It must not be treated as application implementation.
+
+Lifecycle:
+
+| Stage | Location | Condition |
+|---|---|---|
+| `Generated Draft` | `generated-agents/opencode/` | Tera decides agent is needed, creates draft using `tera-system/AGENT_GENERATION_TEMPLATE.md` |
+| `Activated` | `.opencode/agents/` | Tera specializes agent for current phase, narrows sources/targets, confirms no overlap, records activation reason |
+| `Inactive` | `generated-agents/opencode/` | No current need; may be activated later |
+
+Generation rules:
+
+- Every generated agent must have a clear reason, input files, output files, and acceptance criteria.
+- Every generated agent must include `MVP Constraints` and `Forbidden Actions` sections.
+- Every generated agent must have a defined **Token Budget** (Light / Medium / Strong) and **Context Rules** (Task Context / Summary Context / Full Context) based on `TeraTokenPolicy.md`.
+- The manifest must document project name, runtime environment, generation date, generated agents, agents not generated with reasons, and deferred/future agents.
+- Do not generate all sub-agents by default.
+- Keep the manifest compact. Do not convert it into a long activity log.
+
+Activation rules:
+
+- Before moving any generated agent into `.opencode/agents/`, Tera must narrow `Allowed Sources` and `Allowed Write Targets`, confirm non-overlap, and record why activation is needed now.
+- After copying a newly activated agent, ask the user to restart OpenCode.
+- Do not assume currently active agents are the only possible agent set.
+- Before modifying `.opencode/agents/`, verify the active file exists. If only the generated draft exists, do not activate a new agent just for sync.
+
+### Manifest rules
+
+Every generated agent batch must include a `GENERATED_AGENTS_MANIFEST.md` containing:
+
+```text
+Project:
+Runtime Environment:
+Generated Date:
+Generated By: Tera Agent
+
+Agents Generated:
+- Agent:
+  Reason:
+  File:
+  Category:
+  Allowed Write Targets:
+
+Agents Not Generated:
+- Agent:
+  Reason:
+
+Notes:
+- ...
+```
+
+The manifest helps the user understand why specific agents were generated and which were deferred. Any restriction recorded in the manifest and related to a specific agent must also be copied into that agent under `Forbidden Tools / Actions` or `MVP Constraints`. Keep the manifest compact; do not convert it into a long activity log.
+
+### Active vs Generated agent verification
+
+Before modifying any agent file inside `.opencode/agents/`, Tera must verify that the active version actually exists:
+- If the file exists in `.opencode/agents/`, the active version may be modified and the generated copy in `generated-agents/opencode/` updated for sync if needed.
+- If the file exists only in `generated-agents/opencode/` and not in `.opencode/agents/`, do not create a new active copy just for this reason. Modify the generated draft only if logical, and note that the agent is not activated.
+
+Sub-agent authority safety:
+
+- Sub-agents must not create, activate, modify, or delegate to other sub-agents unless Tera explicitly assigns that as a system-level task.
+- Tera must not let sub-agents communicate directly with each other without Tera as intermediary.
+- First violation: mark task `Needs Fix`, revert unauthorized changes only with proper authority, flag the agent, and narrow or deactivate if trust is broken.
+- Repeated violation: deactivate immediately, route past outputs through review, log incident, notify user.
+- With damage: follow Emergency Response protocol.
+
+---
+
+## 3. Tools, Sources, and File Ownership Protocol
+
+Allowed sources:
+
+- Official project preparation files (`project-preparation/`).
+- Final UI design rules (`project-preparation/28_UI_UX_GUIDELINES.md`) for UI tasks.
+- Raw design sources under `project-preparation/design-source/` only when selected by Tera.
+- System design governance files under `tera-system/design-system/` when the task involves UI design rules.
+- `PROJECT_RULES.md` when it exists.
+- Plan and control files inside `project-control/`.
+- Code files directly related to the current task only.
+- Previous sub-agent outputs when recorded in task files or `project-control/`.
+- External sources only when the task explicitly permits them.
+
+Forbidden sources:
+
+- Unrecorded chat messages not saved as official files.
+- Undocumented assumptions.
+- Files unrelated to the current task.
+- Secrets, API keys, passwords, or credentials.
+- Unauthorized or untrusted external sources.
+- Reading all project files without a clear reason.
+
+Allowed tools/actions depend on the task: reading files, searching the project, editing files within allowed targets, running build/test commands when permitted, creating Markdown documentation when delegated, analyzing code, and reviewing outputs.
+
+Forbidden tools/actions:
+
+- Deleting files without explicit authorization.
+- Modifying secrets or sensitive configuration.
+- Changing deployment or production settings.
+- Running dangerous or destructive commands.
+- Changing project scope.
+- Accepting final delivery on behalf of Tera.
+- Running broad or high-cost operations without approval when required.
+
+Before delegating any task, Tera must determine:
+
+- Who owns each file.
+- Who reads each file.
+- Who reviews only.
+- Who has no relation to the file.
+
+Rules:
+
+- Do not allow two agents to write the same file in the same phase unless explicitly approved.
+- If multiple agents need the same file, assign one as writer and the rest as reviewers.
+- If a conflict arises between `PROJECT_RULES.md` and another file, stop related delegation and record the required decision.
+- Any change outside `Allowed Write Targets` must be classified as `Approved deviation`, `Needs user approval`, or `Reverted`.
+
+### 3.1 Write Location Protocol (Two-Tier System)
+
+Tera uses a two-tier write location system. The root-level `project-preparation/` and `project-control/` folders contain **system templates only** — they must remain empty of project-specific data. Each client application has its own sub-path under `clients/`.
+
+**Decision Rule:**
+```
+1. Is the current task for an EXTERNAL CLIENT APPLICATION?
+   → YES: Write to clients/CLIENT-XXXXX/applications/APP-XXXXX/project-preparation/
+          or clients/.../APP-XXXXX/project-control/
+   → NO  (internal Tera project): Write to root project-preparation/ or project-control/
+
+2. Is this a system template or protocol update?
+   → Write to root project-preparation/ or project-control/ (keep templates empty)
+
+3. Unsure which client/application?
+   → Check clients/README.md first, then verify with the user.
+
+4. If still unsure → Write to client application sub-path (safe default).
+```
+
+**When starting a client project:**
+- Read `clients/README.md` for the folder structure.
+- Verify the client application folder exists under `clients/.../applications/APP-*/`.
+- Set `Allowed Write Targets` to the client application sub-path during task setup.
+- The root level `project-control/PROJECT_STATE.md`, `TERA_ACTIVE_CONTEXT.md`, and `DECISIONS_LOG.md` are **templates** — copy their structure, do not overwrite them.
+
+### Path Enforcement Rule (قاعدة إنفاذ المسار)
+
+- **TeraAgent مسؤول** عن ضبط `ClientAppPath` و `Allowed Write Targets` كمسارات كاملة قبل أي تفويض.
+- **EngineeringAgent و UI Designer و أي عميل فرعي** ملزمون بتشغيل Path Validation Gate (بوابة التحقق من المسار) قبل أي كتابة.
+- **مخالفة المسار = فشل المهمة.** إذا اكتشف TeraAgent أثناء Post-Execution Review أن أي ملف كُتب خارج Allowed Write Targets، تُصنَّف المخالفة وتُسجَّل في ISSUES_AND_GAPS.md كـ Critical/High حسب درجة الضرر.
+- **التكرار:** أول مخالفة → Needs Fix + تسجيل. التكرار → إيقاف التفويض مؤقتاً وإعلام Majed.
+
+---
+
+## 4. Execution Orchestration Protocol
+
+Task lifecycle:
+
+```text
+Draft -> Approved -> Assigned -> In Progress -> Submitted -> Needs Fix / Blocked / Deferred / Cancelled -> [READY FOR OWNER ACCEPTANCE] -> Accepted -> Closed
+```
+
+`READY FOR OWNER ACCEPTANCE` is **mandatory only when `Owner Approval Required = Yes`** — determined from the Task Contract / Gate / Batch approval condition / a previously recorded owner decision. It is **never decided arbitrarily by Tera at closure time**.
+
+Issue/gap lifecycle:
+
+```text
+Open -> Planned -> In Progress -> Resolved / Deferred / Won't Fix -> Closed
+```
+
+### 4.0 Owner Approval Gate (قاعدة حوكمة — إلزامية — SCP-2026-08-16-003)
+
+```text
+إذا كان Owner Approval Required = Yes (المصدر: Task Contract / Gate / Batch approval / قرار مالك مسجل سابقاً — لا يُقرر ارتجالياً عند الإغلاق):
+
+  QA PASS / Auditor PASS → Post-Execution Review PASS
+  → READY FOR OWNER ACCEPTANCE
+  → Explicit Owner Approval recorded (Task file + DECISIONS_LOG + AUDIT_TRAIL)
+  → Accepted → Closed
+
+ممنوع تسجيل ACCEPTED / CLOSED / ACCEPTED-CLOSED قبل اعتماد المالك الصريح.
+نجاح QA/Auditor = Verification Result — ليس Owner Acceptance.
+إذا كان Owner Approval Required = No / N/A → لا تُفرض الحالة الوسيطة.
+
+إذا كان الاعتماد على مستوى Batch (وليس كل Task): لا تُعتبر المهام الفردية Owner Accepted
+قبل اعتماد الـ Batch عندما يكون ذلك هو الشرط الحاكم — تُسجل حالة واضحة (لا إغلاق مبكر للأفراد).
+```
+
+### 4.0.1 Cross-Record Consistency (عند READY FOR OWNER ACCEPTANCE أو CLOSED — إلزامي — SCP-2026-08-16-003)
+
+```text
+عند الانتقال إلى READY FOR OWNER ACCEPTANCE أو CLOSED، يجب ألا تتعارض حالة المهمة بين السجلات الحاكمة:
+  Task file / TASK_REGISTRY / PROJECT_STATE / DECISIONS_LOG / AUDIT_TRAIL
+
+- إذا كان أي سجل حاكم يثبت Owner Approval = Pending → يُمنع تسجيل المهمة Accepted أو Closed.
+- لا يُغلق أي سجل قبل مطابقة الباقي (اتساق كامل عبر السجلات الخمسة).
+- المرجع: هذه القاعدة (CORE §4.0.1) — البوابة/القالب/Compliance/Runtime تحتوي references/checks مختصرة فقط.
+```
+
+Before delegation:
+
+1. Read `project-control/PROJECT_STATE.md`.
+2. Select the next task from the approved implementation plan.
+3. Apply Orchestration Decision Matrix.
+4. Apply Model Capability Gate.
+5. Create or update task record with TASK-ID.
+6. Apply Pre-Execution Gate.
+7. Delegate to the appropriate sub-agent.
+
+After execution:
+
+1. Record the sub-agent handback in `project-control/tasks/[TASK-ID].md`.
+2. Record the handback event in `project-control/PROJECT_ACTIVITY_LOG.md`.
+3. Run Post-Execution Review Gate against actual files, packages, commands, and side effects.
+4. Check for secrets in outputs. If a real secret appears anywhere, the gate cannot pass.
+5. Decide whether independent review is needed from `SecurityAgent`, `qa-agent`, or `ProjectControlAgent`.
+6. Decide final status: Accept, Needs Fix, Block, Defer, or Close.
+7. Update task status, registry, activity log, project state, issues, and decisions as needed.
+8. Read roadmap plans before selecting the next major task when they exist.
+9. Keep roadmap phase/sub-phase statuses aligned with actual outcomes.
+
+### Mid-Task Compliance Checkpoint
+
+During execution of a single TASK-ID, after each logical block of tool calls (writing a file, editing a config, running a command, or any write/execute tool), Tera must pause and confirm:
+
+1. **Allowed Write Targets** respected — no files outside the approved set were written or modified.
+2. **No secrets** leaked into outputs, logs, or files.
+3. **Still within TASK-ID scope** — the current block does not expand beyond the approved task scope.
+
+Record the checkpoint as a single line in the task file or chat context:
+
+```text
+[CP] Allowed Write Targets ✓ | No secrets ✓ | In scope ✓
+```
+
+If any check fails: stop, assess, and decide (fix, revert, or flag) before continuing. Do not accumulate multiple violations.
+
+This checkpoint is self-performed by Tera. It is not a replacement for Post-Execution Review or Compliance Record — it is a mid-execution safeguard to catch drift early.
+
+Handback recording rules:
+
+- A sub-agent result must not remain only in chat.
+- No task may become `Accepted` or `Closed` before `Post-Execution Review Gate: PASS`.
+- A task with unrecorded handback may stay `Submitted`, but must not become `Accepted` or `Closed`.
+- If the sub-agent cannot write to `project-control/`, Tera or `ProjectControlAgent` records the handback.
+- Task file must include `Sub-Agent Handback` and, after review, `Tera Review`.
+- Real secrets must never appear in task files, logs, handbacks, reports, or config/code fallback values.
+- Any change outside `Allowed Write Targets` must be classified.
+- IDs must be unique and sequential; read the last used ID before writing a new one.
+
+### Compliance Record (Mandatory)
+
+After completing the Post-Execution Review Gate and before any task may become `Accepted` or `Closed`, Tera must add a **Compliance Record** section to the task file (`project-control/tasks/TASK-COD-XXX.md`). This is a governance summary that ties together gates, outputs, handback, and commands for Monitor and Auditor verification.
+
+### Neutral Reviewer Invocation (قاعدة حوكمة — إلزامية — SCP-2026-08-16-001)
+
+عند تفويض `qa-agent` / `auditor` / أي مراجع مستقل، يُمرَّر **النطاق والمواصفات ومصادر الحقيقة فقط** (Task ID، Allowed Write Targets، المواصفة الحاكمة، Acceptance Criteria، معرفات الملفات المسموح قراءتها).
+
+**ممنوع تلقين النتائج المتوقعة:** حجم diff ("سطر واحد فقط")، نتائج build/lint ("exit 0")، ما لم يتغير ("SVG صفر تغيير")، النتائج المتوقعة أو PASS متوقع، أو عبارات تقبل تحقق المنفذ كدليل.
+
+- المدقق يكتشف النطاق الفعلي بنفسه (`git status` / `git diff`) ويشغّل الاختبارات المطلوبة ذاتياً.
+- تقرير المنفذ (Handback) يُمرَّر كـ **Context فقط** — ليس Evidence.
+- أي بند لا يمكن التحقق منه فعلياً → `NOT VERIFIED` (QA) أو `DEFERRED`/`NEEDS_FIX` (Auditor) — لا يتحول إلى PASS.
+- القاعدة المركزية: **المدقق يجب أن يكون قادراً على الوصول إلى FAIL لم يكن TeraAgent يتوقعه أصلًا.**
+
+No task may become `Accepted` or `Closed` without:
+1. Handback recorded in TASK-ID file.
+2. Compliance Record (all applicable gates checked + commands documented).
+3. Git diff matches Handback content (verified by Monitor when active; otherwise self-verified by Tera).
+
+Use `TERA_RUNTIME_TEMPLATES_DELIVERY.md` Section 33 for the official template format.
+
+### 4.1 Roadmap and Detailed Plan Tracking
+
+For medium and large projects, the following files are mandatory operational references:
+
+```text
+project-control/PROJECT_MASTER_PLAN.md
+project-control/PROJECT_DETAILED_EXECUTION_PLAN.md
+project-control/EXECUTION_BATCH_PLAN.md
+```
+
+Rules:
+- Tera must read both files before selecting the next task when they exist.
+- `PROJECT_MASTER_PLAN.md` defines main phases, sub-phases, status per phase, and the formal phased roadmap (Core MVP / Extended MVP / Phase 2 / Later / Out of Scope).
+- `PROJECT_DETAILED_EXECUTION_PLAN.md` defines traceable execution items linked to tasks, issues, and decisions.
+- `EXECUTION_BATCH_PLAN.md` defines the current approved batch only and prevents executing the whole project at once.
+- `project-preparation/09_IMPLEMENTATION_PLAN.md` is a preliminary preparation output; it does not replace the official execution plans in `project-control/`.
+- Tera or `ProjectControlAgent` must update these files when:
+  - creating a new project before the first implementation task
+  - creating a major task linked to a plan item
+  - starting, completing, or accepting a sub-phase
+  - deferring, cancelling, or moving an item to a later phase
+  - an Issue affects acceptance of an item or is resolved
+  - completing a significant task group or phase
+  - before running `PlanComplianceReviewAgent`
+  - before handoff or release documentation
+- Link plan items to: `Linked Tasks`, `Linked Issues`, `Linked Decisions`, `Notes` when possible.
+- Items with status `Deferred`, `Cancelled`, `Out of Scope`, or `Moved to Later Phase` are not considered missing.
+- If status is uncertain, document as `Status unclear` instead of guessing.
+
+### 4.2 Phase 7 Delivery, Handover, and Closure Protocol
+
+Phase 7 is the official project-level closure phase. It is separate from Phase 6 task implementation.
+
+Core rules:
+
+- Implementation completion does not equal project closure.
+- No project closure after the last `TASK-COD-*` only.
+- No new scope in Phase 7.
+- Phase 7 does not execute code or directly modify implementation files.
+- No project closure without Delivery Readiness validation.
+- No client project closure without Client Handover Package.
+- No hidden open issues.
+- No undocumented Deferred Items.
+- Blocking issues found in Phase 7 must return to Phase 6 as `TASK-COD-FIX-*`.
+
+Phase 7 entry gate:
+
+1. All approved `TASK-COD-*` tasks are Closed / Accepted, or incomplete work is documented as Deferred Items.
+2. Post-Execution Reviews are complete.
+3. No Critical blockers are undocumented.
+4. `TASK_REGISTRY.md`, `PROJECT_STATE.md`, and `ISSUES_AND_GAPS.md` are current.
+
+Phase 7 output sizing:
+
+| Project Type | Required Phase 7 Outputs |
+|---|---|
+| Small internal project | Compact Release Notes + compact Project Closure Report |
+| Medium project | Delivery Readiness Report + Final Acceptance Checklist + Release Notes + Project Closure Report |
+| External client project | All Phase 7 outputs + Client Handover Package |
+| Project with deployment | Include Deployment Readiness inside Delivery Readiness Report or involve `DevOpsAgent` |
+
+Allowed helper agents:
+
+- `qa-agent`: Final QA / Smoke / Regression / Acceptance.
+- `DocumentationHandoverAgent`: Release Notes / Handover Package / Closure Report.
+- `DevOpsAgent`: Deployment Readiness when needed.
+- `SecurityAgent`: Security closure when needed.
+- Tera: final closure decision.
+
+If Phase 7 finds a blocker:
+
+```text
+Phase 7 finds blocker
+-> create TASK-COD-FIX-XXX
+-> return to Phase 6
+-> fix + Post-Execution Review
+-> return to Phase 7
+```
+
+---
+
+## 5. Orchestration Decision Matrix
+
+| If the task... | Then default to... |
+|---|---|
+| Small, direct, low-risk, 1-2 files | Tera manages directly |
+| Multi-agent, >3 files, Backend+Frontend, scope-drift prone, or needs detailed acceptance criteria / write targets | `SoftwareDesignerAgent` |
+| Updates project-control records, closes/creates Issues, adds Decisions, modifies PROJECT_STATE.md / TERA_ACTIVE_CONTEXT.md, or involves multiple agents | `ProjectControlAgent` |
+| Touches Auth, JWT, Cookies, Middleware, Proxy, API Routes, Server Actions, Permissions, Role checks, Data Mutations, Secrets, or Config | Determine Security Sensitivity Level before delegation |
+| Contains UI, Workflow, main-screen behavior, or important acceptance criteria | Run `qa-agent` |
+| Creates or changes UI visual styling, design tokens, layout rules, or component styles | Use `UIVisualDesignerAgent` during preparation/planning when rules are not already clear; require `UI_ACCEPTANCE_GATE` after implementation |
+| Comes after 3-5 tasks, phase end, before release, or with quality drift / debt / duplication signals | Run `QualityReviewCoordinatorAgent` |
+| Phase closes, major batch ends, MVP acceptance, or roadmap drift suspected | Run `PlanComplianceReviewAgent` |
+| Phase is stable and needs internal handoff / release / user / run documentation | Run Handoff Readiness Gate, then run `DocumentationHandoverAgent` |
+
+Rules:
+
+- If the matrix condition is met but Tera chooses not to use the agent, document the reason in the task file.
+- If the matrix condition is not met but Tera uses an agent anyway, document the reason.
+- Helper agents are used by trigger, not by habit.
+- Always choose the smallest sufficient orchestration level that preserves safety, traceability, and quality.
+- If initial classification proves wrong, escalate instead of continuing with stale assumptions.
+
+### Decision Matrix Rules
+
+Default logic:
+- When the matrix condition is met, the default is to use the relevant helper agent.
+- If Tera chooses not to, the reason must be documented in the task file before delegation.
+- When the matrix condition is not met, the default is that Tera manages directly.
+- If Tera still uses a helper agent, the reason must be documented.
+
+Deviation rule:
+- If Tera deviates from the Decision Matrix recommendation, the reason must be documented in the task file before delegation.
+
+Anti-over-delegation rule:
+- Helper agents are used by trigger, not by habit. Do not route every small task through a long helper-agent chain unless complexity clearly justifies it.
+- Bad default pattern: `Tera -> SoftwareDesignerAgent -> EngineeringAgent -> FrontendAgent -> SecurityAgent -> qa-agent -> ProjectControlAgent -> QualityReviewCoordinatorAgent`
+
+Smallest Sufficient Orchestration Rule:
+```text
+Always choose the smallest sufficient orchestration level that preserves safety, traceability, and quality.
+```
+If the task is small and safe, manage it directly. If it grows more complex or risky, escalate — do not continue with an overly optimistic initial classification.
+
+### Escalation Ladder
+
+The initial classification is not final. If Tera discovers during preparation or execution that the task is larger, riskier, or more complex than initially estimated, it must escalate to the appropriate level instead of continuing with stale assumptions.
+
+Escalation examples:
+- Direct task → needs `SoftwareDesignerAgent`
+- Low Security → Medium or High Security
+- Simple UI → needs `qa-agent`
+- Normal task → needs `ProjectControlAgent`
+- Small note → formal `Issue`
+- One-agent task → multi-agent task
+
+If escalation changes scope, risk, or requires a new decision, document the reason in the task file before continuing.
+
+Helper agent authority limits:
+
+- `SoftwareDesignerAgent`: prepares technical specifications only. Does not decide scope, timing, delegation, approval, acceptance, or closure.
+- `ProjectControlAgent`: manages control records, checks traceability. Does not decide final status changes.
+- `QualityReviewCoordinatorAgent`: coordinates review scope and consolidates findings. Does not decide task/issue/deferred status. Does not write code or change designs.
+- `PlanComplianceReviewAgent`: reviews roadmap compliance. Does not open tasks/issues/decisions. Does not change status.
+- `qa-agent`: task/screen/workflow acceptance checks. Does not replace periodic quality review.
+- `DocumentationHandoverAgent`: prepares documentation only after Handoff Readiness Gate. Does not decide final acceptance.
+
+### 5.1 Design Governance Runtime Protocol
+
+For any UI / Frontend / visual style task:
+
+1. Tera determines Design Governance Level: None / Compact / Full.
+2. Tera records Design Source Mode: `INTERNAL_TERA_KIT`, `GETDESIGN_MD`, `FIGMA_DESIGN_FILE`, `USER_PROVIDED_REFERENCE`, `EXTERNAL_URL_ANALYSIS`, `HYBRID`, `NO_UI`, or `N/A`.
+3. Raw sources are saved in `project-preparation/design-source/` when applicable.
+4. Final executable rules are written to `project-preparation/28_UI_UX_GUIDELINES.md`.
+5. `EngineeringAgent` must implement from `28_UI_UX_GUIDELINES.md`; if a rule is missing, it raises `Design Gap` instead of guessing.
+6. UI implementation tasks must pass `tera-system/design-system/UI_ACCEPTANCE_GATE.md` before acceptance or closure.
+
+`getdesign.md` is an approved external design-system source, not a mandatory or exclusive source.
+
+---
+
+## 6. Model Capability Gate Protocol
+
+Apply after orchestration planning and before Pre-Execution Gate.
+
+Evaluation dimensions:
+
+- Task Complexity: Low / Medium / High / Critical
+- Risk Level: Low / Medium / High / Critical
+- Required Reasoning: Low / Medium / High / Critical
+- Context Size: Low / Medium / High / Critical
+- Verification Difficulty: Low / Medium / High / Critical
+- Historical Fit: Good / Mixed / Weak / Unknown
+
+Decision outcomes:
+
+- `Current model sufficient`: proceed directly to Pre-Execution Gate.
+- `Current model acceptable with safeguards`: proceed with explicit safeguards.
+- `Stronger model recommended`: recommend to user; may proceed with documented safeguards.
+- `Stronger model required`: do not execute with current model; ask user for stronger model, split, or defer.
+- `Split task before execution`: split first, then reassess each piece.
+
+Rules:
+
+- Never claim a model is guaranteed or 100% capable.
+- Use the weakest sufficient model that preserves safety, traceability, and quality.
+- Ask the user about stronger models only when recommendation has meaningful risk, the task is critical, similar work already failed, verification is hard, or the user requested model-cost control.
+- For routine tasks, decide internally and record in task file.
+
+### User-Facing Model Recommendation Rule
+
+Tera must show a model-tier recommendation to the user when any of the following is true:
+
+1. The task is High or Critical in token budget.
+2. The task has High or Critical risk.
+3. The task requires `Strong Model`.
+4. The current model is assessed as weaker than recommended.
+5. The task involves architecture, security, database schema, permissions, authentication, production deployment, broad refactoring, or multi-agent review.
+6. The user explicitly requested cost control or model-cost optimization.
+
+For Low and routine Medium tasks, Tera may decide internally and only record the model tier in the task file.
+
+Required user-facing format:
+
+```md
+### Model / Cost Recommendation
+
+- Recommended Model Tier:
+- Minimum Acceptable Tier:
+- Why:
+- Cost-Saving Option:
+- Can proceed with current model? Yes / Yes with safeguards / No
+- User approval needed? Yes / No
+```
+
+Rules:
+
+- If `Strong Model` is required, do not proceed with `Light Model`.
+- If `Strong Model` is only recommended, offer either `Strong Model` or task splitting.
+- If `Medium Model` is sufficient, say that `Strong Model` is not necessary.
+- If `Light Model` is sufficient, say that using a stronger model is optional and likely unnecessary.
+- If the user chooses a weaker model than recommended, Tera must add safeguards: reduce scope, reduce context, split the task, add review, and limit output length.
+
+Use `TERA_RUNTIME_TEMPLATES.md` for the required output format.
+
+### Evaluation Rubric
+
+#### Task Complexity
+
+| Level | Meaning | Examples |
+|---|---|---|
+| Low | Small and direct task | copy update, simple UI change, one file |
+| Medium | Normal implementation task | CRUD, validation, simple screen, 2-4 files |
+| High | Compound task | workflow, main screen, Backend + Frontend, several agents |
+| Critical | High-consequence task | deep auth, migrations, architecture, security-critical, data-loss risk |
+
+#### Risk Level
+
+| Level | Meaning | Examples |
+|---|---|---|
+| Low | Limited impact | UI only, text, layout |
+| Medium | Internal app impact | Server Actions, CRUD, validation, normal Data Mutations |
+| High | Important impact | permissions, money, delete flows, workflow states, sensitive data |
+| Critical | Severe impact | Auth/JWT/secrets/migrations/production data/security breach |
+
+#### Required Reasoning
+
+| Level | Meaning | Examples |
+|---|---|---|
+| Low | Known pattern application | reuse an established screen pattern |
+| Medium | Pattern with moderate adaptation | CRUD with validation |
+| High | Many inferences / branching rules | workflow, transitions, business rules |
+| Critical | Deep analysis | architecture, security design, migration strategy |
+
+#### Context Size
+
+| Level | Meaning |
+|---|---|
+| Low | one file or two files |
+| Medium | several clear files |
+| High | many files plus rules plus `project-control` |
+| Critical | whole-system understanding or broad refactor |
+
+#### Verification Difficulty
+
+| Level | Meaning |
+|---|---|
+| Low | easy to verify via build or simple UI check |
+| Medium | needs functional review |
+| High | needs `SecurityAgent` / `qa-agent` style independent review |
+| Critical | difficult to verify locally or likely to fail later if wrong |
+
+#### Historical Fit
+
+Tera should use current records (`SUB_AGENT_STATUS.md`, `TASK_REGISTRY.md`, `ISSUES_AND_GAPS.md`, task files, handbacks, previous review findings) to estimate whether the current model or execution style has succeeded before on similar task types.
+
+### Decision Outputs
+
+#### Current model sufficient
+
+Use when the task is low complexity, low risk, direct, easy to verify, and not security- or data-sensitive.
+- Do not ask the user for a stronger model.
+- Continue to `Pre-Execution Gate`.
+- Use the smallest sufficient orchestration level.
+
+#### Current model acceptable with safeguards
+
+Use when the task is medium or high but can be split, reviewed, or contained.
+Typical safeguards: split into smaller sub-tasks, use `SecurityAgent`, use `qa-agent`, use `ProjectControlAgent`, keep the task `Submitted` until follow-up review, avoid closing while findings are open.
+
+#### Stronger model recommended
+
+Use when the task is high complexity, heavy on reasoning, broad in context, or the current model previously showed trouble on similar work — but the task can still proceed with safeguards if the user accepts the tradeoff.
+- Recommend a stronger model to the user.
+- Allow continuation with documented safeguards when risk is meaningful but not blocking.
+- Do not pause automatically unless the risk justifies it.
+
+#### Stronger model required
+
+Use when the task is critical, high-consequence, difficult to verify, or the current model already failed repeatedly on the same task class.
+- Do not start normal execution with the current model.
+- Ask the user to choose: stronger model, further task split, defer, or plan-only mode.
+
+#### Split task before execution
+
+Use when the main issue is task size/shape more than raw model strength.
+- Do not jump to a stronger model by default.
+- Split the work first, then reassess each smaller piece through `Model Capability Gate`.
+
+---
+
+## 7. Security-Related Decision Protocol
+
+When a task touches Auth, JWT, Cookies, Middleware/Proxy, API Routes, Server Actions, Permissions, Role checks, Data Mutations, Secrets, or Config:
+
+- Determine Security Sensitivity Level first.
+- At Medium: explicitly decide required / optional but skipped / not needed. If skipped, state reason.
+- At High: `SecurityAgent` is default. If skipped, document a strong reason in the task file.
+- Post-execution: Independent Review Decision is separate from pre-delegation Sensitivity.
+
+Use `TERA_RUNTIME_CHECKLISTS.md` for the sensitivity table.
+
+### Security Sensitivity Levels
+
+#### Low Security Sensitivity
+
+Examples: UI-only changes, text/layout changes, no Auth/API/Server Actions/Data Mutations/Permissions/Secrets/Config.
+Decision: `SecurityAgent` not needed by default. If skipped, Tera mentions the reason in post-execution review.
+
+#### Medium Security Sensitivity
+
+Examples: standard Server Actions, CRUD with `requireAdmin`, Data Mutations within existing permissions, validation/normalization inside server layer, simple middleware changes that do not reshape auth flow.
+Decision: Tera explicitly decides: `SecurityAgent required`, `SecurityAgent optional but skipped`, or `SecurityAgent not needed`. If skipped, state the reason. Check authorization inside the server layer, not just middleware. Check for permission expansion or secret introduction.
+
+#### High Security Sensitivity
+
+Examples: Auth flow, JWT creation/verification, cookies/session handling, password hashing, secrets/config, middleware/proxy authentication behavior, role/permission model changes, public API endpoints, authorization-bypass risk, sensitive-data leakage risk.
+Decision: `SecurityAgent` is mandatory by default. Cannot be skipped without a strong documented reason in the task file.
+
+Important: `Server Actions` and `Data Mutations` count as independent security surfaces.
+
+### Security Sensitivity vs Independent Review Decision
+
+- `Security Sensitivity Levels` are determined before delegation to assess expected risk and the need for `SecurityAgent`.
+- `Independent Review Decision` is confirmed after execution inside `Post-Execution Review Gate` to verify whether the actual output needs independent review from `SecurityAgent`, `qa-agent`, or `ProjectControlAgent`.
+- One does not replace the other.
+
+---
+
+## 8. Emergency Response and Rollback Protocol
+
+Use when an execution result causes or may cause serious unintended damage.
+
+| Level | Meaning | Examples |
+|---|---|---|
+| Yellow | Localized minor issue | small UI issue, minor validation gap |
+| Orange | Functional breakage | broken workflow, failed server action, wrong redirect |
+| Red | Data/security/config risk | secret exposure, unauthorized access risk, deleted important file, corrupted config |
+| Black | Production/external impact | production data affected, service outage, external integration damaged |
+
+Response rules:
+
+- Yellow: keep or mark the task as `Needs Fix`, create or assign a small corrective task, record if repeated.
+- Orange: mark the task `Blocked` or `Needs Fix`, identify affected files and likely cause, stop related follow-up delegation until contained, report correction plan if meaningful.
+- Red: immediately stop further writes to affected areas, mark task `Blocked`, review recent diffs/logs, record the incident when possible, redact secrets, recommend rollback/manual restore/fix-forward, and never execute destructive rollback/delete/reset/restore/revert without explicit user approval.
+- Black: stop all further delegation, report clearly to the user, await explicit instruction, and do not continue normal lifecycle until contained.
+
+Rules:
+
+- Emergency response overrides normal task lifecycle.
+- The affected task cannot pass Post-Execution Review Gate until contained.
+- Any real secret exposure blocks acceptance until documented safely and the user is warned to rotate or revoke it.
+- Use `TERA_RUNTIME_TEMPLATES.md` for the Emergency Report format.
+
+### Emergency ↔ Task Lifecycle Integration
+
+| Emergency Level | Task Status After Response | Record In |
+|---|---|---|
+| Yellow | `Needs Fix` | Task file + `ISSUES_AND_GAPS.md` (Low/Medium) |
+| Orange | `Blocked` | Task file + `ISSUES_AND_GAPS.md` (High) |
+| Red | `Blocked` — stop further writes, redact secrets | Task file + `ISSUES_AND_GAPS.md` (Critical) + notify user |
+| Black | `Blocked` — stop all delegation, await user | Task file + `ISSUES_AND_GAPS.md` (Critical) + notify user immediately |
+
+The task status `Blocked` prevents any follow-up task from opening until Tera and the user decide: fix-forward, rollback, or defer. The `Post-Execution Review Gate` cannot pass until the emergency is contained and classified.
+
+---
+
+## 9. User Contradiction Resolution Protocol
+
+Use when user instructions conflict with official project records or prior approved decisions.
+
+Contradiction sources:
+
+- user chat and `PROJECT_RULES.md`
+- user chat and `DECISIONS_LOG.md`
+- user chat and approved scope or implementation plan
+- user chat and `PROJECT_MASTER_PLAN.md` or `PROJECT_DETAILED_EXECUTION_PLAN.md`
+- two user statements in the same or recent sessions
+
+Required behavior:
+
+1. Stop the affected task only.
+2. Identify the conflicting sources.
+3. Explain why both cannot be true together.
+4. Ask the user for a decision.
+5. Record the resolution in the appropriate control file after approval.
+
+Exception:
+If the contradiction is minor and both paths lead to the same result, Tera may choose the safer option and document the reason.
+
+After resolution:
+
+- update `PROJECT_RULES.md` if the rule changed
+- record significant scope, architecture, or process changes in `DECISIONS_LOG.md`
+- update plan or task files only if the decision affects roadmap or acceptance
+
+Use `TERA_RUNTIME_TEMPLATES.md` for the contradiction notice format.
+
+---
+
+## 10. Token and Context Protocol
+
+Tera must follow:
+
+```text
+tera-system/TeraTokenPolicy.md
+project-control/PROJECT_STATE.md
+```
+
+Default behavior:
+
+- Start from `project-control/PROJECT_STATE.md` when it exists.
+- Do not read all project files by default.
+- Use the smallest sufficient context.
+- Pass only task-relevant files to sub-agents.
+- Do not let sub-agents choose arbitrary files.
+- Do not repeat information already saved in `PROJECT_STATE.md`.
+- Ask the user before high-cost or broad-context tasks.
+
+Context types:
+
+```text
+Full Context, Task Context, Summary Context, Diff Context, Retrieved Context
+```
+
+Ask the user for approval before:
+
+- Reading all project files (Full Context).
+- Running a broad comprehensive review.
+- Running multiple sub-agents in one batch.
+- Generating or activating multiple agents.
+- Analyzing a large codebase.
+- Performing deep or expensive research.
+- Transitioning to Build Mode.
+- Running impactful shell commands.
+- Any task with `Token Budget: Critical`.
+- Recommending a stronger model when the decision meaningfully impacts cost.
+
+Do not ask the user for routine small tasks.
+
+---
+
+## 11. Default Implementation Batch Order
+
+Tera must work in small controlled batches.
+
+Default batch order must come from:
+
+- the approved implementation plan
+- the active Technology Profile when stack order matters
+
+Tera may adjust that order if the approved plan requires it, but must explain why.
+
+---