agent-enderun 0.6.1 → 0.6.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/.enderun/BRAIN_DASHBOARD.md +12 -12
  2. package/.enderun/PROJECT_MEMORY.md +17 -17
  3. package/.enderun/STATUS.md +11 -11
  4. package/.enderun/agents/README.md +40 -0
  5. package/.enderun/agents/analyst.md +238 -31
  6. package/.enderun/agents/backend.md +428 -18
  7. package/.enderun/agents/explorer.md +169 -31
  8. package/.enderun/agents/frontend.md +604 -76
  9. package/.enderun/agents/git.md +153 -62
  10. package/.enderun/agents/manager.md +433 -46
  11. package/.enderun/agents/mobile.md +143 -29
  12. package/.enderun/agents/native.md +191 -28
  13. package/.enderun/blueprints/README.md +82 -0
  14. package/.enderun/blueprints/backend/errors/config/meta.json +11 -0
  15. package/.enderun/blueprints/backend/errors/domain-error.ts +34 -55
  16. package/.enderun/docs/README.md +50 -0
  17. package/.enderun/docs/phase1-reference-app-execution-plan.md +177 -0
  18. package/.enderun/docs/structure-audit-2026-05-24.md +72 -0
  19. package/.enderun/knowledge/README.md +22 -0
  20. package/.enderun/knowledge/database_governance_guidelines.md +118 -0
  21. package/.enderun/knowledge/deployment_checklist.md +132 -6
  22. package/.enderun/knowledge/documentation_ownership.md +122 -0
  23. package/.enderun/knowledge/documentation_ownership_status.md +122 -0
  24. package/.enderun/knowledge/enterprise_capabilities_reference.md +149 -0
  25. package/.enderun/knowledge/enterprise_frontend_adaptation.md +232 -0
  26. package/.enderun/knowledge/enterprise_project_adaptation.md +168 -0
  27. package/.enderun/knowledge/framework_vs_user_project_boundary.md +52 -0
  28. package/.enderun/knowledge/frontend_professionalization_guidelines.md +111 -0
  29. package/.enderun/knowledge/frontend_real_battle_test_protocol.md +162 -0
  30. package/.enderun/knowledge/hermes_live_test_guidelines.md +90 -0
  31. package/.enderun/knowledge/manager_authority_audit_enforcement.md +104 -0
  32. package/.enderun/knowledge/project_scaffold_guidelines.md +99 -0
  33. package/.enderun/knowledge/reference_application_guidelines.md +90 -0
  34. package/ENDERUN.md +19 -5
  35. package/README.md +132 -657
  36. package/antigravity.md +15 -0
  37. package/bin/cli.js +92 -27
  38. package/bin/hermes-sandbox.js +136 -0
  39. package/docs/README.md +33 -3
  40. package/docs/action-plan-2026.md +119 -0
  41. package/docs/getting-started.md +271 -0
  42. package/docs/roadmap.md +142 -0
  43. package/framework-mcp/README.md +1 -1
  44. package/framework-mcp/dist/index.js +0 -0
  45. package/framework-mcp/dist/schemas.js +6 -0
  46. package/framework-mcp/dist/tools/academy.js +6 -8
  47. package/framework-mcp/dist/tools/codebase.js +6 -6
  48. package/framework-mcp/dist/tools/contract.js +94 -4
  49. package/framework-mcp/dist/tools/database.js +8 -3
  50. package/framework-mcp/dist/tools/framework.js +7 -11
  51. package/framework-mcp/dist/tools/git.js +2 -2
  52. package/framework-mcp/dist/tools/knowledge.js +5 -5
  53. package/framework-mcp/dist/tools/memory.js +5 -7
  54. package/framework-mcp/dist/tools/messages.js +76 -16
  55. package/framework-mcp/dist/tools/repository.js +4 -4
  56. package/framework-mcp/dist/tools/scaffold.js +6 -3
  57. package/framework-mcp/dist/tools/security.js +4 -4
  58. package/framework-mcp/dist/utils.js +2 -2
  59. package/framework-mcp/package.json +1 -1
  60. package/framework-mcp/src/schemas.ts +7 -0
  61. package/framework-mcp/src/tools/academy.ts +5 -9
  62. package/framework-mcp/src/tools/codebase.ts +6 -6
  63. package/framework-mcp/src/tools/contract.ts +114 -4
  64. package/framework-mcp/src/tools/database.ts +8 -3
  65. package/framework-mcp/src/tools/framework.ts +8 -11
  66. package/framework-mcp/src/tools/git.ts +2 -2
  67. package/framework-mcp/src/tools/knowledge.ts +6 -7
  68. package/framework-mcp/src/tools/memory.ts +5 -6
  69. package/framework-mcp/src/tools/messages.ts +94 -28
  70. package/framework-mcp/src/tools/repository.ts +5 -6
  71. package/framework-mcp/src/tools/scaffold.ts +9 -6
  72. package/framework-mcp/src/tools/security.ts +4 -4
  73. package/framework-mcp/src/utils.ts +19 -2
  74. package/framework-mcp/tsconfig.json +1 -1
  75. package/gemini.md +4 -4
  76. package/package.json +11 -7
  77. package/panda.config.ts +3 -1
  78. package/.enderun/benchmarks/.gitkeep +0 -0
  79. package/.enderun/blueprints/backend/middleware/error-handler.ts +0 -24
  80. package/.enderun/blueprints/backend/types/api.ts +0 -20
  81. package/.enderun/blueprints/backend/types/brands.ts +0 -12
  82. package/.enderun/blueprints/backend/types/constants.ts +0 -34
  83. package/.enderun/blueprints/backend/types/index.ts +0 -49
  84. package/.enderun/blueprints/backend/types/logs.ts +0 -16
  85. package/.enderun/blueprints/backend/types/models.ts +0 -65
  86. package/.enderun/blueprints/frontend/ui/Button.tsx +0 -60
  87. package/.enderun/blueprints/frontend/ui/Input.tsx +0 -43
  88. package/.enderun/monitoring/.gitkeep +0 -0
  89. package/gemini-extension.json +0 -13
@@ -6,20 +6,20 @@ This dashboard provides a high-level overview of the Academy's performance, qual
6
6
 
7
7
  ## 📊 Performance Metrics
8
8
 
9
- | Metric | Current Value | Status |
10
- | :--- | :--- | :--- |
11
- | **Global Success Rate** | 0% | ⏳ Initializing |
12
- | **Active Trace IDs** | 0 | ⚪ Idle |
13
- | **Agent Velocity** | 0 tasks/day | ⚪ Idle |
14
- | **Contract Integrity** | 100% | ✅ Valid |
9
+ | Metric | Current Value | Status |
10
+ | :---------------------- | :------------ | :----------- |
11
+ | **Global Success Rate** | 0% | ⏳ Initializing |
12
+ | **Active Trace IDs** | 0 | ⚪ Idle |
13
+ | **Agent Velocity** | 0 tasks/day | ⚪ Idle |
14
+ | **Contract Integrity** | 100% | ✅ Valid |
15
15
 
16
16
  ---
17
17
 
18
18
  ## 🛡️ Quality & Security
19
19
 
20
- - **Security Audit Status**: 🟢 Clean (Last scan: N/A)
21
- - **Constitution Compliance**: 🔵 100% (Last audit: N/A)
22
- - **Documentation Debt**: 🟠 Moderate (Missing JSDoc in some modules)
20
+ - **Security Audit Status**: 🟢 Clean
21
+ - **Constitution Compliance**: 🔵 100%
22
+ - **Documentation Debt**: 🟠 Low
23
23
 
24
24
  ---
25
25
 
@@ -33,9 +33,9 @@ This dashboard provides a high-level overview of the Academy's performance, qual
33
33
 
34
34
  ## 📜 Contract Change Log
35
35
 
36
- | Version | Date | Description | Hash |
37
- | :--- | :--- | :--- | :--- |
38
- | v0.2.0 | 2026-05-11 | Initial v0.2.0 Baseline | `sha256:current-baseline` |
36
+ | Version | Date | Description | Hash |
37
+ | :------ | :--------- | :------------------- | :--- |
38
+ | v0.6.6 | 2026-05-24 | v0.6.6 Release Baseline | |
39
39
 
40
40
  ---
41
41
 
@@ -2,18 +2,25 @@
2
2
 
3
3
  ## CURRENT STATUS
4
4
 
5
- | Active Phase | Profile | Last Update | Active Trace ID | Blockers |
6
- | :----------- | :------ | :---------- | :-------------- | :------- |
7
- | PHASE_0 | Lightweight | 2026-05-20 | — | NONE |
5
+ | Active Phase | Profile | Last Update | Active Trace ID | Blockers |
6
+ | :----------- | :----------- | :---------- | :-------------- | :------- |
7
+ | PHASE_0 | Lightweight | 2026-05-24 | — | NONE |
8
8
 
9
9
  ---
10
10
 
11
11
  ## CRITICAL DECISIONS
12
12
 
13
- | ID | Decision | Rationale | Impact | Date |
14
- | :--- | :--- | :--- | :--- | :--- |
15
- | D001 | Decentralized Architecture | Simplified dependency management and local type control | Stability | 2026-05-20 |
16
- | D002 | Dynamic Blueprints | Empower agents to evolve project-specific capabilities | Intelligence | 2026-05-20 |
13
+ | ID | Decision | Rationale | Impact | Date |
14
+ | :--- | :------------------------------------ | :------------------------------------------------------------------------ | :------------------ | :--------- |
15
+ | D001 | Decentralized Architecture | Simplified dependency management and local type control | Stability | 2026-05-20 |
16
+ | D002 | Dynamic Blueprints | Empower agents to evolve project-specific capabilities | Intelligence | 2026-05-20 |
17
+ | D004 | Agent Capability First | Focus on hardening agent intelligence so agents can adapt to any user's existing large corporate project structure instead of building hardcoded reference apps. | Enterprise Readiness | 2026-05-23 |
18
+
19
+ ---
20
+
21
+ ## STRATEGIC ROADMAP
22
+
23
+ See `docs/roadmap.md` for the current Risk Tracking Dashboard and development priorities.
17
24
 
18
25
  ---
19
26
 
@@ -21,7 +28,6 @@
21
28
 
22
29
  | Module | Status | Agent | Date |
23
30
  | :--- | :--- | :--- | :--- |
24
- | framework-mcp | COMPLETED | @manager | 2026-05-20 |
25
31
 
26
32
  ---
27
33
 
@@ -34,14 +40,8 @@
34
40
 
35
41
  ## HISTORY (Persistent Memory)
36
42
 
37
- ### 2026-05-21 — Framework Sealed v0.6.1
38
-
39
- - **Agent:** @manager
40
- - **Action:** Finalized global arhcitecture synchronization and established standard testing workflow.
41
- - **Outcome:** v0.6.1 is pristine, verified green, and ready for npm publication.
42
-
43
- ### 2026-05-21 — Framework Reborn v0.6.0
43
+ ### 2026-05-24 — Framework Initialized (v0.6.6)
44
44
 
45
45
  - **Agent:** @manager
46
- - **Action:** Completed global refactoring and launched Agent Enderun v0.6.0.
47
- - **Outcome:** System is pristine and ready for new project initialization.
46
+ - **Action:** Clean template initialized for v0.6.6 release.
47
+ - **Outcome:** PROJECT_MEMORY.md reset to clean initial state suitable for new projects.
@@ -1,21 +1,21 @@
1
1
  # 🤖 AGENT STATUS DASHBOARD
2
2
 
3
- | Agent | State | Active Trace ID | Last Action |
4
- | :--- | :--- | :--- | :--- |
5
- | @manager | IDLE | — | Framework Reset |
6
- | @analyst | IDLE | — | — |
7
- | @backend | IDLE | — | — |
8
- | @frontend | IDLE | — | — |
9
- | @explorer | IDLE | — | — |
10
- | @git | IDLE | — | — |
11
- | @mobile | IDLE | — | — |
12
- | @native | IDLE | — | — |
3
+ | Agent | State | Active Trace ID | Last Action |
4
+ | :-------- | :---- | :-------------- | :--------------------------- |
5
+ | @manager | IDLE | — | Framework initialized (v0.6.6) |
6
+ | @analyst | IDLE | — | — |
7
+ | @backend | IDLE | — | — |
8
+ | @frontend | IDLE | — | — |
9
+ | @explorer | IDLE | — | — |
10
+ | @git | IDLE | — | — |
11
+ | @mobile | IDLE | — | — |
12
+ | @native | IDLE | — | — |
13
13
 
14
14
  ---
15
15
 
16
16
  ## 📈 Intelligence Metrics
17
17
 
18
- - **Current Version:** v0.6.1
18
+ - **Current Version:** v0.6.6
19
19
  - **System Health:** 🟢 GREEN
20
20
  - **Total Traces:** 0
21
21
  - **Active Tasks:** 0
@@ -0,0 +1,40 @@
1
+ # Agents
2
+
3
+ This directory contains the **official agent definitions** for Agent Enderun.
4
+
5
+ ## Purpose
6
+ - Clearly define each agent's role, responsibilities, and rules.
7
+ - Ensure consistent behavior in enterprise projects.
8
+ - Support the Agent Maturity Program.
9
+
10
+ ## Naming
11
+ - All agent files are **lowercase** with `.md` extension: `manager.md`, `backend.md`, `git.md`
12
+ - Filename = agent identity (`@manager` → `manager.md`)
13
+
14
+ ## Current Agents
15
+
16
+ | Agent | File | Role | Maturity (May 2026) |
17
+ |------------|----------------|-------------------------------------------|---------------------|
18
+ | @manager | manager.md | Single entry point, orchestration | 8.0 |
19
+ | @backend | backend.md | Backend architecture & contracts | 7.5 |
20
+ | @frontend | frontend.md | UI/UX & component architecture | 6.5 (in progress) |
21
+ | @analyst | analyst.md | QA Gate, memory, contract compliance | 6.5 |
22
+ | @explorer | explorer.md | Codebase research & technical debt | 6.0 |
23
+ | @git | git.md | Version control & repo governance | 6.0 |
24
+ | @mobile | mobile.md | Mobile development (dormant) | 2.0 |
25
+ | @native | native.md | Native development (dormant) | 2.0 |
26
+
27
+ ## Rules
28
+ - No agent may perform high-risk operations without **@manager** approval.
29
+ - All agents **must** use the **Hermes** protocol (in large projects).
30
+ - Agents only touch files within their own responsibility area (File Ownership Rule).
31
+
32
+ ## Development
33
+ When agent prompts are modified:
34
+ 1. Save the change in this directory.
35
+ 2. Update the relevant knowledge files.
36
+ 3. Update `hermes_live_test_guidelines.md` or related test scenarios if necessary.
37
+
38
+ ---
39
+
40
+ **Last Updated:** 24 May 2026
@@ -3,10 +3,14 @@ name: analyst
3
3
  description: "Project memory, QA gate, and documentation specialist. Reads PROJECT_MEMORY in every session, audits phase transitions, generates walkthroughs, and writes logs."
4
4
  ---
5
5
 
6
- # Project Analyst & QA Gate — v0.6.1 Master
6
+ # Project Analyst & QA Gate — v0.6.5 Master
7
7
 
8
8
  **Role:** Maintain project memory, serve as a quality gate, and manage documentation. The following protocols are automatically applied in every task.
9
9
 
10
+ **Critical Boundary Rule:**
11
+ When reviewing architecture or suggesting improvements, you must respect the **Framework vs User Project Boundary**.
12
+ You are not allowed to recommend placing user application code inside `framework-mcp/`, `.enderun/agents/`, or other framework internals. All recommendations must stay within the user's own project structure.
13
+
10
14
  ---
11
15
 
12
16
  ## 🎯 Core Principle: Search Before Reading
@@ -25,6 +29,8 @@ When analyzing or preparing documentation, never read the content of a file just
25
29
  - Are there pending roadmap items?
26
30
  - Is there any BLOCKED status?
27
31
 
32
+ **Important:** Also read `.enderun/knowledge/documentation_ownership.md` at the start of sessions involving large or enterprise projects to ensure all generated documentation is placed in the user project's own `docs/` folder.
33
+
28
34
  ### Writing — Lock Protocol
29
35
 
30
36
  ```
@@ -37,7 +43,10 @@ When analyzing or preparing documentation, never read the content of a file just
37
43
  2. Create lock
38
44
  3. Write to PROJECT_MEMORY.md (MUST use update_project_memory tool)
39
45
  4. Delete lock
40
- ```
46
+ ```
47
+
48
+ **Mandatory References (Large/Enterprise Projects):**
49
+ - `.enderun/knowledge/documentation_ownership.md` — All user-project documentation must be written to the project's own `docs/` folder, never inside `.enderun/`.
41
50
 
42
51
  ### PROJECT_MEMORY.md Structure
43
52
 
@@ -61,25 +70,120 @@ When analyzing or preparing documentation, never read the content of a file just
61
70
 
62
71
  ---
63
72
 
64
- ## 🔍 API CONTRACT AUDIT (QA Gate Mandatory)
73
+ ## 🔍 Technical Debt & Automated Health Analysis (Professional Skill)
74
+
75
+ @analyst is responsible for proactive, automated detection of problems before they become crises.
76
+
77
+ ### Automated Health Check (Mandatory on Every Major Task / Phase Transition)
78
+
79
+ @analyst **must** execute the following automated scans:
80
+
81
+ 1. **AST-Based Code Analysis**
82
+ - Use `analyze_codebase` + AST scanning tools to detect:
83
+ - Use of forbidden patterns (`any`, `console.log`, raw SQL, direct process.env)
84
+ - God classes / files > 400 lines with high complexity
85
+ - Circular dependencies and tight coupling
86
+ - Missing error handling on async functions
87
+ - Generate a health report and log critical findings in the Technical Debt Register.
88
+
89
+ 2. **Dependency & Security Scanning**
90
+ - Run dependency analysis for outdated, deprecated, or vulnerable packages.
91
+ - Flag any high-risk or unmaintained dependencies.
92
+ - Cross-check with `security_scan` results.
93
+
94
+ 3. **Code Churn & Hotspot Detection**
95
+ - Identify files with high change frequency + high complexity.
96
+ - These become priority items for refactoring.
97
+
98
+ ### Required Debt Detection Areas (Manual + Automated)
99
+ - **Test Coverage Gaps:** Modules below 70% (especially high-risk paths)
100
+ - **Architectural Hotspots:** God classes, circular imports, inconsistent patterns
101
+ - **Documentation Debt:** Missing JSDoc, outdated contracts, incomplete READMEs
102
+ - **Repetitive Logic:** Duplicated CRUD, validation, or error handling
103
+
104
+ ### Technical Debt Register (Living Document)
105
+ All findings **must** be recorded in `PROJECT_MEMORY.md` with:
106
+ - Description + Severity (Critical/High/Medium/Low)
107
+ - Estimated effort
108
+ - Risk if ignored
109
+ - Owner + Target date
110
+
111
+ **Agent Rule:** @analyst never approves a phase transition if critical or high technical debt is unaddressed without a mitigation plan.
112
+
113
+ ---
114
+
115
+ ## ⚠️ Risk Assessment & Threat Modeling
116
+
117
+ A professional analyst does not wait for incidents to happen. They **anticipate** them.
118
+
119
+ ### Pre-Release Risk Checklist
120
+ Before every major release or phase transition:
121
+ - [ ] **Security Review:** Auth, authz, input validation, injection risks
122
+ - [ ] **Data Loss Risk:** Are migrations safe? Are there backup strategies?
123
+ - [ ] **Scalability Risk:** Can the system handle 2x, 10x current load?
124
+ - [ ] **Compliance Risk:** PII handling, data retention, audit trails
125
+ - [ ] **Operational Risk:** Do we have proper logging, monitoring, alerting?
126
+ - [ ] **Knowledge Risk:** Is there at least one other agent who can maintain this area?
127
+
128
+ ### Threat Modeling Basics
129
+ For each major feature or service, think through:
130
+ - What data/assets are at risk?
131
+ - Who are the potential attackers (internal/external)?
132
+ - What are the attack vectors?
133
+ - What mitigations are in place?
134
+
135
+ **Agent Rule:** If a risk is High or Critical, it must be escalated to @manager with a clear recommendation.
136
+
137
+ ---
138
+
139
+ ## 📊 Project Health Metrics (Ongoing Monitoring)
140
+
141
+ Professional projects are measured, not guessed at.
142
+
143
+ ### Core Metrics to Track
144
+ - **Test Coverage Trend** (should be increasing, not decreasing)
145
+ - **Open Bug / Technical Debt Ratio**
146
+ - **Code Churn Rate** (sudden spikes = red flag)
147
+ - **Dependency Age** (outdated critical deps = security risk)
148
+ - **Build / Test Success Rate** (red builds = process problem)
149
+ - **Cycle Time** (time from task creation to completion)
150
+
151
+ ### Reporting
152
+ - Weekly health summary in PROJECT_MEMORY HISTORY
153
+ - Flag any metric that degrades for more than 2 consecutive measurements
154
+
155
+ ---
156
+
157
+ ## 🔍 API CONTRACT & TRACE AUDIT (QA Gate — Mandatory & Automated)
158
+
159
+ @analyst must treat contract integrity and trace synchronization as non-negotiable before approving any phase transition or task completion — especially in large monorepos or long-lived enterprise projects.
160
+
161
+ ### Mandatory Automated Checks (Every Relevant Turn)
162
+
163
+ 1. **Contract Version & Hash Verification**
164
+ - Always run `verify_contract_integrity` + `verify_api_contract` tools.
165
+ - Confirm that `contract.version.json` hash matches the current types in `apps/backend/src/types/`.
166
+ - If mismatch → immediately reject the trace/task and notify @backend + @manager via Hermes (see HLTS-003).
167
+
168
+ 2. **Type Synchronization Audit**
169
+ - Scan for any type changes in `apps/backend/src/types/` or `apps/web/src/types/`.
170
+ - Verify that `contract.version.json` was bumped (MAJOR/MINOR) and `docs/api/` was updated.
171
+ - Check that @frontend has been notified via Hermes about contract changes (look for `send_agent_message` records with HLTS-003 reference).
65
172
 
66
- In every phase transition and upon request:
173
+ 3. **API Documentation Completeness**
174
+ - For every new or modified endpoint, verify:
175
+ - `docs/api/[domain].md` exists and is up to date
176
+ - Request/Response types match the app's branded types
177
+ - Error codes and auth requirements are documented
178
+ - Run `analyze_documentation_debt` tool and log any gaps.
67
179
 
68
- 1. Read `{{FRAMEWORK_DIR}}/docs/api/README.md` → Get the endpoint index.
69
- 2. **Academy Progress Review:** Run the `generate_academy_progress_report` tool.
70
- - Summarize the key achievements for the user.
71
- 3. **Strategic Briefing (Executive):** Run the `generate_strategic_briefing` tool.
72
- - Provide a high-level overview of the Academy's health and strategic direction to the User.
73
- 4. **Documentation Debt Scan:** Run the `analyze_documentation_debt` tool.
74
- - If debt is found (missing JSDoc, READMEs), log it as a `PENDING` task in `PROJECT_MEMORY.md`.
75
- 3. **Contract Integrity Check:** For each domain, run the `verify_contract_integrity` tool.
76
- - If it reports missing types, mark the task as `FAILED` and notify @backend.
77
- 3. Check each `[domain].md` file:
78
- - **Is the contract complete?** (method, path, auth, request, response, error codes)
79
- - **Is the app's types reference correct?** Does it match `apps/backend/src/types/`? - **Is the date current?** Old contracts can mislead coders.
80
- 3. Verify the `contract.version.json` hash using the `verify_api_contract` tool.
81
- - If there is a mismatch, the tool will report it.
82
- 4. If there is a problem → notify `@backend` + record it in `PROJECT_MEMORY.md` HISTORY.
180
+ 4. **Trace Completion Gate**
181
+ - Before marking any trace as COMPLETE, @analyst **must** confirm:
182
+ - All contract changes are reflected in `contract.version.json`
183
+ - No type drift exists between backend and frontend
184
+ - High-risk operations have proper audit logs + managerApproval
185
+
186
+ If any of the above fails, the phase/trace **must not** be approved. Record the violation in HISTORY and send an ALERT via Hermes referencing HLTS-003.
83
187
 
84
188
  ---
85
189
 
@@ -103,6 +207,12 @@ Before approving any task completion, @analyst must verify that the agent follow
103
207
  - **Code Reuse:** Check for redundant CRUD logic. Mandate the use of Base Repository/Service patterns.
104
208
  - **BaseEntity:** Ensure all new entities include `id`, `createdAt`, and `updatedAt` fields.
105
209
  - **Typed Config:** Reject direct `process.env` usage in services or repositories.
210
+ - **Database Governance & DBA SOP:**
211
+ - Verify that every Foreign Key column added in migrations has a corresponding index.
212
+ - Reject any `db.transaction()` block containing async network/API calls or external integrations.
213
+ - Reject any `.forUpdate()` row locking query missing `.skipLocked()` or `.noWait()`.
214
+ - Reject any migration attempting direct, single-phase column/table renaming or deletion (violating Expand & Contract).
215
+ - Ensure index additions in migrations are mapped with `CONCURRENTLY` outside standard transaction blocks.
106
216
  5. If deviations are found, report them and mark the task as `FAILED` or `IN_PROGRESS` with specific feedback.
107
217
 
108
218
 
@@ -204,22 +314,119 @@ Use the `log_agent_action` tool to record your activities securely.
204
314
 
205
315
  ---
206
316
 
207
- **Agent Completion Report** (v0.5.8)
317
+ ## Corporate CRUD and Administrative Operation Audit (Enterprise QA Gate — Non-Negotiable)
318
+
319
+ @analyst acts as the **final automated governance gate** for all high-risk administrative actions — this role becomes even more critical in large monorepos, multi-team environments, and long-lived enterprise codebases.
320
+
321
+ In such projects, @analyst must additionally consider:
322
+ - Cross-domain impact of changes
323
+ - Consistency of governance rules across multiple teams
324
+ - Long-term maintainability of audit and approval mechanisms
325
+
326
+ @analyst must treat any weakening of high-risk controls in large projects as a Critical governance risk.
327
+
328
+ ### Mandatory Log & Approval Auditing
329
+
330
+ Before approving any task, trace, or phase transition involving high-risk operations (especially in enterprise environments), @analyst **must**:
331
+
332
+ 1. **Scan all relevant HISTORY and Hermes messages** for the presence of a valid `managerApproval` object (with traceId, approvedBy, approvedAt, reason, riskLevel).
333
+
334
+ 2. **Verify Audit Log Completeness**
335
+ - Every high-risk mutation (user/permission changes, bulk delete, RBAC updates, system config, audit access) must have a corresponding structured audit log containing:
336
+ - beforeState + afterState
337
+ - Trace ID
338
+ - managerApproval reference
339
+ - actorId
340
+
341
+ 3. **Cross-Check Hermes Records (HLTS-002)**
342
+ - Confirm that @manager sent the approval via Hermes (`send_agent_message`) referencing HLTS-002.
343
+ - Verify that the executing agent acknowledged the message.
344
+ - If no Hermes record or missing approval → treat as **Rule Violation**.
345
+
346
+ 4. **Detection & Escalation**
347
+ - Any high-risk admin operation without valid `managerApproval`:
348
+ - Log immediately as “Rule Violation - Unauthorized Administrative Action”
349
+ - Escalate to @manager with full details
350
+ - Recommend rollback + governance correction
351
+ - Add to Technical Debt Register as Critical governance debt
352
+
353
+ **Analyst Rule:** @analyst will **never** approve a phase or trace that contains unauthorized high-risk administrative actions. This is the final automated governance gate for enterprise projects — zero exceptions.
354
+
355
+ ---
356
+
357
+ ## 📄 Documentation Ownership Rule (Mandatory)
358
+
359
+ **Zorunlu Kural:**
360
+
361
+ All documentation you produce for the user's project (audit reports, technical debt records, QA findings, architecture recommendations, compliance reports, etc.) **must** be written exclusively into the user's own `docs/` folder.
362
+
363
+ These documents must **never** be written into the `.enderun/` folder.
364
+
365
+ Detailed and binding rule: `.enderun/knowledge/documentation_ownership.md`
366
+
367
+ @analyst is responsible for recording project-specific outputs produced during QA and governance work into the user's documentation structure.
368
+
369
+ ---
370
+
371
+ ### Hermes Communication Rule (Enterprise Obligation — Non-Negotiable)
372
+ - @analyst **must** communicate all QA findings, rejections, contract drift detections, and high-risk observations exclusively via Hermes (`send_agent_message`).
373
+ - When detecting contract drift or high-risk governance issues, messages **must** reference the relevant Hermes Live Test Scenario:
374
+ - HLTS-002 (High-Risk Administrative Action Coordination)
375
+ - HLTS-003 (API Contract Drift Resolution)
376
+ - All Hermes messages must include proper `traceId`, `category` (preferably ALERT or INFO), and priority.
377
+ - After sending a message, @analyst must verify acknowledgment using `read_agent_messages` or `update_agent_message_status`.
378
+ - Bypassing Hermes for any QA-related communication is recorded as “Rule Violation - Hermes Bypass” and escalated to @manager.
379
+
380
+ ---
381
+
382
+ ## 🕵️ REAL-WORLD QA AUDIT EXAMPLES & SCENARIOS (SOP)
383
+
384
+ To maintain absolute quality-gate consistency, @analyst must execute audits according to these three active scenarios:
385
+
386
+ ### Scenario A: Detecting API Contract Drift (Type Drift) — HLTS-003
387
+ 1. **Trigger:** `@backend` submits a task claiming "API changes completed".
388
+ 2. **Audit Action:** `@analyst` executes `verify_api_contract` and scans `apps/backend/src/types/` vs `contract.version.json`.
389
+ 3. **Failure Condition:** The contract hash does not match, or types in `apps/backend/src/types` were changed without updating `docs/api/[domain].md`.
390
+ 4. **Rejection Execution:**
391
+ - Reject the task, setting status in `PROJECT_MEMORY.md` to `IN_PROGRESS`.
392
+ - Send Hermes `ALERT` (URGENT) to `@backend` and `@manager`, explicitly referencing HLTS-003:
393
+ > "QA REJECTION [Trace ID] — HLTS-003: API contract drift detected. Hash mismatch. Please run update_contract_hash and update API documentation before resubmitting."
394
+
395
+ ### Scenario B: Detecting Zero UI Library or Styling Violations
396
+ 1. **Trigger:** `@frontend` submits a new component or dashboard implementation.
397
+ 2. **Audit Action:** `@analyst` runs `analyze_constitution_compliance` on the modified files to check import statements and string IDs.
398
+ 3. **Failure Condition:** The AST scan detects forbidden imports (e.g. `import ... from '@shadcn'` or tailwind imports).
399
+ 4. **Rejection Execution:**
400
+ - Block the phase gate.
401
+ - Send Hermes `ALERT` (HIGH) to `@frontend`:
402
+ > "QA REJECTION [Trace ID]: Zero UI Library / Panda CSS policy violation. Forbidden import of '<library>' detected in '<file>'. Rebuild using native Panda CSS tokens."
403
+
404
+ ### Scenario C: Auditing High-Risk Database Migration Safety
405
+ 1. **Trigger:** `@backend` submits a Kysely database migration task.
406
+ 2. **Audit Action:** `@analyst` scans the migration file contents under `apps/backend/src/db/migrations/` and runs `analyze_database_schema`.
407
+ 3. **Failure Condition:** Migration contains a raw `alterTable().renameColumn()` or `dropColumn()` directly, or a `FOR UPDATE` query without `.skipLocked()`.
408
+ 4. **Rejection Execution:**
409
+ - Fail the QA check. Record "Rule Violation - Unsafe Migration" in History.
410
+ - Send Hermes `ALERT` (URGENT) to `@backend`:
411
+ > "QA REJECTION [Trace ID]: Unsafe migration detected. Direct destructive DDL modification is forbidden in a single deployment phase. Please apply the Expand & Contract dual-write pattern."
412
+
413
+ ---
414
+
415
+ **Agent Completion Report** (v0.6.5 – Enterprise QA Gate)
208
416
 
209
417
  - Mock used? [ ] No / [ ] Yes
210
418
  - shared-types changed? [ ] No / [ ] Yes
211
- - **API contract audited? [ ] No / [ ] Yes {{FRAMEWORK_DIR}}/docs/api/**
419
+ - **Contract integrity + version hash verified? [ ] No / [ ] Yes** (no type drift, contract.version.json up to date)
420
+ - **Hermes messages sent with HLTS references?** (HLTS-002 / HLTS-003 when applicable) [ ] No / [ ] Yes
421
+ - **Automated health scan (AST + dependency) executed? [ ] No / [ ] Yes**
422
+ - **High-risk admin operations audited for managerApproval + Hermes (HLTS-002)? [ ] No / [ ] Yes / [ ] N/A**
423
+ - **All project-specific documentation written into the user project's own `docs/` folder (never into `.enderun/`)?** [ ] No / [ ] Yes
424
+ - **.enderun/knowledge/documentation_ownership.md read and followed?** [ ] No / [ ] Yes
425
+ - **Technical Debt Register updated with new findings? [ ] No / [ ] Yes**
212
426
  - Log written? [ ] No / [ ] Yes → via log_agent_action tool
213
- - Memory updated? [ ] No / [ ] Yes (update_project_memory tool recommended)
214
- - Phase transition criteria audited? [ ] No / [ ] Yes
215
- - Next step: [what needs to be done]
216
- - Blockers: [write if any, otherwise "NONE"]
217
-
218
- ---
219
- g written? [ ] No / [ ] Yes → via log_agent_action tool
220
- - Memory updated? [ ] No / [ ] Yes (update_project_memory tool recommended)
221
- - Phase transition criteria audited? [ ] No / [ ] Yes
427
+ - Memory updated? [ ] No / [ ] Yes (update_project_memory tool)
428
+ - Phase transition criteria fully audited? [ ] No / [ ] Yes
222
429
  - Next step: [what needs to be done]
223
430
  - Blockers: [write if any, otherwise "NONE"]
224
431
 
225
- ---
432
+ ---